# List orders by invoice

By using this method, merchants can retrieve a list of orders associated with a particular invoice.

Endpoint: POST /subscription/order/list
Version: 1.0.0
Security: MerchantID

## Header parameters:

  - `merchant` (string, required)
    Unique public key provided upon registration and must be shared for identification purposes.
    Example: "api_pk_7b197...ba108f842"

  - `signature` (string, required)
    Request signature that allows verification of merchant authenticity on the payment gateway server.
    Example: "M2E3OTkyNzcz...xMmExODI4"

## Request fields (application/json):

  - `invoice_id` (string, required)
    Unique invoice identifier associated with a specific subscription.
    Example: "83b19018-cbc4-45f0-899a-dda84fd2705e"

  - `pagination` (object)
    Contains information about the pagination of the results.


  Should be provided together if either of the key-value pairs, offset or limit, is included in the object. For the key-value pair that is not needed, specify its default value.

  - `pagination.offset` (integer, required)
    Starting index of the results to return.
    Example: 20

  - `pagination.limit` (integer, required)
    Maximum number of items to return.
    Example: 10

## Response 200 fields (application/json):

  - `data` (array, required)
    List of orders, each containing attributes like order identifier, status, type, amount, currency, and timestamps for creation and updates.

  - `data.id` (string, required)
    Unique order identifier, which can be used to find the payment.


  For the first payment, the identifier is defined by the merchant.
  For recurring subscription-based payments, it is generated by the Solidgate subscription service.
    Example: "1672066481283AlexKho"

  - `data.status` (string, required)
    Status of the requested order.


  Card order statuses are created, processing, 3ds_verify, auth_ok, auth_failed, void_ok, settle_ok, and refunded. Card order status partial_settled is not used in subscriptions.
  
  APM order statuses are created, processing, approved, declined, and refunded. APM order status settle_pending is not used in subscriptions.
    Enum: "created", "processing", "3ds_verify", "auth_ok", "auth_failed", "void_ok", "settle_ok", "refunded", "approved", "declined"

  - `data.created_at` (string, required)
    Datetime of the order creation.
    Example: "2025-12-27 11:45:30"

  - `data.updated_at` (string, required)
    Datetime of the order update.
    Example: "2025-12-27 11:46:30"

  - `data.processed_at` (string)
    Datetime when the order was processed.


  It is empty for orders in processing.
    Example: "2025-12-28 11:45:30"

  - `data.amount` (integer, required)
    Original order amount.
    Example: 100

  - `data.payment_details` (object)
    Details of the payer for transactions conducted through APMs.


  It provides essential information like the customer's email and the invoice identifier, both of which are specifically applicable to transactions conducted with the PayPal method.

  - `data.payment_details.invoice_id` (string)
    Unique invoice identifier provided by PayPal.


  It is provided only for transactions with paypal-vault method.
    Example: "123443334"

  - `data.payment_details.payer_email` (string)
    Customer's email.


  It is provided only for transactions with paypal-vault method.
    Example: "example@example.com"

  - `data.retry_attempt` (integer)
    Indicates the number of retry attempts for the invoice.


  Filled for orders created according to retry strategy.

  - `data.operation` (string)
    Type of the transaction.
    Enum: "pay", "recurring", "recurring-auth", "refund", "resign", "resign-auth", "auth", "settle", "void", "apple-pay", "google-pay"

  - `pagination` (object, required)
    Contains information about the pagination of the results.

  - `pagination.offset` (integer, required)
    Starting index of the returned results.
    Example: 20

  - `pagination.limit` (integer, required)
    Maximum number of items to return.
    Example: 10

  - `pagination.total_count` (integer, required)
    Total count of the subscription invoices.
    Example: 150

## Response 400 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code.
    Example: "2.01"

  - `error.message` (string, required)
    Error message.
    Example: "Validation error"

  - `error.constraints` (object)
    Map of constraints.

## Response 401 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating the specific authorization failure.
    Example: "1.01"

  - `error.message` (string, required)
    Descriptive message providing more details about the authorization failure.
    Example: "Authorization failed"

## Response 403 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating that access to the service is denied.
    Example: "1.02"

  - `error.message` (string, required)
    Message informing that the service is not allowed for the account.
    Example: "Access denied"

## Response 404 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code.
    Example: "2.01"

  - `error.message` (string, required)
    Error message.
    Example: "{entityName} not found with id: {entityId}"