# Retrieve subscriptions by customer

This method allows the merchant to retrieve all subscriptions and their statuses for the specific customer by the customer identifier.

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

  - `customer_account_id` (string, required)
    Unique customer identifier defined by the merchant.
    Example: "93a1c659-288d-4d62-929d-10e241078faa"

## Response 200 fields (application/json):

  - `body` (object) — one of:
    - Success:
      - `<subscription_id_value_#1>` (object)
        Details of a subscription, including payment and customer information.
      - `<subscription_id_value_#1>.id` (string, required)
        Unique subscription identifier.
        Example: "64e1c283-17bf-45a7-90ea-2cb938081b2f"
      - `<subscription_id_value_#1>.status` (string, required)
        Subscription status.
        Enum: "pending", "active", "cancelled", "redemption", "paused", "expired"
      - `<subscription_id_value_#1>.started_at` (string, required)
        Datetime of the subscription start.
        Example: "2025-06-10 15:42:24"
      - `<subscription_id_value_#1>.updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-06-10 15:42:25"
      - `<subscription_id_value_#1>.expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-09-10 16:42:24"
      - `<subscription_id_value_#1>.next_charge_at` (string)
        Datetime of the subsequent charge.
        Example: "2025-11-26 11:43:52"
      - `<subscription_id_value_#1>.payment_type` (string, required)
        Customer payment method used to pay for a subscription.
        Example: "paypal-vault"
      - `<subscription_id_value_#1>.trial` (boolean, required)
        Indicates whether the subscription has a trial.
        Example: true
      - `<subscription_id_value_#1>.cancelled_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-06-26 06:43:58"
      - `<subscription_id_value_#1>.cancellation_requested_at` (string)
        Datetime of subscription cancellation request.
        Example: "2025-06-25 06:43:58"
      - `<subscription_id_value_#1>.cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: "8.01", "8.02", "8.03", "8.04", "8.05", "8.06", "8.07", "8.08", "8.09", "8.10", "8.11", "8.12", "8.13", "8.14", "8.15"
      - `<subscription_id_value_#1>.cancel_message` (string)
        Cancellation reason brief description.
        Example: "Card brand is not supported"
      - `<subscription_id_value_#1>.customer` (object, required)
        Customer details related to the subscription, including key information such as the customer's email address.
      - `<subscription_id_value_#1>.customer.customer_account_id` (string, required)
        Unique customer identifier defined by the merchant.
        Example: "93a1c659-288d-4d62-929d-10e241078faa"
      - `<subscription_id_value_#1>.customer.customer_email` (string, required)
        Customer's email address.
        Example: "example@example.com"
      - `<subscription_id_value_#1>.pause` (object)
        Pause schedule parameters.
      - `<subscription_id_value_#1>.pause.from_date` (string, required)
        Pause start date.
        Example: "2025-03-27 11:26:08"
      - `<subscription_id_value_#1>.pause.to_date` (string)
        Pause end date.
        Example: "2025-03-27 11:26:08"
      - `<subscription_id_value_#2>` (object)
        Details of a subscription, including payment and customer information.
      - `<subscription_id_value_#2>.id` (string, required)
        Unique subscription identifier.
        Example: "64e1c283-17bf-45a7-90ea-2cb938081b2f"
      - `<subscription_id_value_#2>.status` (string, required)
        Subscription status.
        Enum: same as `<subscription_id_value_#1>.status` in "Success" (6 values)
      - `<subscription_id_value_#2>.started_at` (string, required)
        Datetime of the subscription start.
        Example: "2025-06-10 15:42:24"
      - `<subscription_id_value_#2>.updated_at` (string, required)
        Datetime of the subscription update.
        Example: "2025-06-10 15:42:25"
      - `<subscription_id_value_#2>.expired_at` (string)
        Datetime of the subscription expiration.
        Example: "2025-09-10 16:42:24"
      - `<subscription_id_value_#2>.next_charge_at` (string)
        Datetime of the subsequent charge.
        Example: "2025-11-26 11:43:52"
      - `<subscription_id_value_#2>.payment_type` (string, required)
        Customer payment method used to pay for a subscription.
        Example: "paypal-vault"
      - `<subscription_id_value_#2>.trial` (boolean, required)
        Indicates whether the subscription has a trial.
        Example: true
      - `<subscription_id_value_#2>.cancelled_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-06-26 06:43:58"
      - `<subscription_id_value_#2>.cancellation_requested_at` (string)
        Datetime of subscription cancellation.
        Example: "2025-06-25 06:43:58"
      - `<subscription_id_value_#2>.cancel_code` (string)
        Reason code that is used to cancel the subscription.
        Enum: same as `<subscription_id_value_#1>.cancel_code` in "Success" (15 values)
      - `<subscription_id_value_#2>.cancel_message` (string)
        Cancellation reason brief description.
        Example: "Card brand is not supported"
      - `<subscription_id_value_#2>.customer` (object, required)
        Customer details related to the subscription, including key information such as the customer's email address.
      - `<subscription_id_value_#2>.customer.customer_account_id` (string, required)
        Unique customer identifier defined by the merchant.
        Example: "93a1c659-288d-4d62-929d-10e241078faa"
      - `<subscription_id_value_#2>.customer.customer_email` (string, required)
        Customer's email address.
        Example: "example@example.com"
      - `<subscription_id_value_#2>.pause` (object)
        Pause schedule parameters.
      - `<subscription_id_value_#2>.pause.from_date` (string, required)
        Pause start date.
        Example: "2025-03-27 11:26:08"
      - `<subscription_id_value_#2>.pause.to_date` (string)
        Pause end date.
        Example: "2025-03-27 11:26:08"
    - Error:
      - `error` (object)
        Error object.
      - `error.code` (string, required)
        Error code that identifies the validation failure.


  This code is returned when the input data does not meet the expected criteria.
        Enum: "2.01"
      - `error.messages` (object, required)
        Contains field-specific error messages.


  Each key is a field name. Each value is an array of strings that describe validation issues.
        Example: {"subscription":["Validation error"]}

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