# List invoices by subscription

By using this method, merchants can get a list of invoices related to a specific subscription.

Endpoint: POST /subscription/invoice/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):

  - `subscription_id` (string, required)
    Unique subscription identifier.
    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 invoices, each representing a billing event for a subscription.

  - `data.id` (string, required)
    Unique invoice identifier.
    Example: "4022a203-ace8-415f-9ae7-730014fceb25"

  - `data.status` (string, required)
    Invoice status.
    Enum: "processing", "retry", "success", "fail"

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

  - `data.updated_at` (string, required)
    Datetime of the invoice update.
    Example: "2025-12-28 11:45:30"

  - `data.amount` (integer, required)
    Current subscription price.
    Example: 100

  - `data.product_price_id` (string)
    Unique product price identifier applied to the invoice. Use it to distinguish
prices configured for different currencies and locations within the
same product for product and price management.


  null is returned if the product has no prices configured for
  other currencies and locations.
    Example: "61b7f690-242a-498c-99a1-eb191f93f08c"

  - `data.billing_period_started_at` (string)
    Start datetime of the period for which the invoice was paid.


  Filled if invoice is in the success status.
    Example: "2025-12-29 11:45:30"

  - `data.billing_period_ended_at` (string)
    End datetime of the period for which the invoice was paid.


  Filled if invoice is in the success status.
    Example: "2025-12-30 11:45:30"

  - `data.subscription_term_number` (integer)
    Indicates the number of passed subscription periods, excluding the trial period. The value increments when a new billing period begins or when the subscription is upgraded or downgraded with a billing period change.
  
  
    Filled if invoice is created:
    
      before March 1, 2024 only for the invoice with a success status
      on or after March 1, 2024, regardless of the invoice status
    Example: 1

  - `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}"