# Retrieve subscriptions by customer

This method allows the merchant to <a href="https://docs.solidgate.com/billing/subscriptions/subscriptions-1.0/manage-subscription/retrieve-subscription-data/#by-customer-id" target="_blank">retrieve all subscriptions</a> 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)

  - `signature` (string, required)

## 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):

  - `<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: "pending", "active", "cancelled", "redemption", "paused", "expired"

  - `<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: "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_#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` (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"

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

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