---
updatedAt: 2025-11-13T21:59:06.000Z
agentTools:
  projectIndex: https://developer.ezypay.com/llms.txt
---

# List subscriptions

Get a list of subscriptions for a specific merchant by customer, status and/or null payment methods. The subscriptions are returned sorted by creation date, with the most recently created subscription appearing first.

By default only 10 record will be listed, if the limit is not set when the API is being triggered.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "billing",
    "version": "2.1.0"
  },
  "servers": [
    {
      "url": "https://api-sandbox.ezypay.com/v2"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/billing/subscriptions": {
      "get": {
        "summary": "List subscriptions",
        "description": "Get a list of subscriptions for a specific merchant by customer, status and/or null payment methods. The subscriptions are returned sorted by creation date, with the most recently created subscription appearing first.\n\nBy default only 10 record will be listed, if the limit is not set when the API is being triggered.",
        "operationId": "list-subscriptions",
        "parameters": [
          {
            "name": "customerId",
            "in": "query",
            "description": "Auto-generated UUID identifier of the customer.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter subscriptions by status. Accepted values are `ACTIVE`, `FUTURE`, `PENDING`, `PAST_DUE`, `PENDING_CANCELLATION`, `CANCELLED` and `COMPLETED`.",
            "schema": {
              "type": "string",
              "default": "ACTIVE"
            }
          },
          {
            "name": "filterNullPaymentMethods",
            "in": "query",
            "description": "Filter for only subscriptions that have null payment methods. Default value is false.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "To paginate a large result set, use the 'limit' argument to limit the number of results returned per page up to a maximum of 100 records. For example, `limit = 10` shows results 1-10. The default returned result would be 100.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "An cursor for use in pagination. Specify the number of objects to skip to fetch the next page of objects. For example, limit=10 and cursor=10 will show results for record 11 - 20.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "merchant",
            "in": "header",
            "description": "Merchant ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"data\": [\n        {\n            \"id\": \"9dc406b2-ec31-455d-9997-ccc9fae91064\",\n            \"customerId\": \"c68510ee-cbff-4f02-bc70-4e09b3197fca\",\n            \"planId\": \"c0ad2142-60e1-47e5-9d78-f6b5f1d09d19\",\n            \"name\": \"high_st_monthly_plan\",\n            \"status\": \"ACTIVE\",\n            \"startDate\": \"2020-02-19\",\n            \"endDate\": null,\n            \"paymentMethodToken\": \"5c4ab365-b000-48e6-b14c-eea9e97797f3\",\n            \"accountingCode\": \"customer_plan\",\n            \"amount\": {\n                \"currency\": \"AUD\",\n                \"value\": 200.00,\n                \"type\": null\n            },\n            \"tax\": {\n                \"rate\": 0.00\n            },\n            \"nextBillingDate\": \"2020-04-01\",\n            \"nextFutureInvoice\": {\n                \"subscriptionId\": \"9dc406b2-ec31-455d-9997-ccc9fae91064\",\n                \"date\": \"2020-04-01\",\n                \"cycleStartDate\": \"2020-04-01\",\n                \"cycleEndDate\": \"2020-04-30\",\n                \"items\": [\n                    {\n                        \"description\": \"high_st_monthly_plan\",\n                        \"amount\": {\n                            \"currency\": \"AUD\",\n                            \"value\": 200.00,\n                            \"type\": null\n                        },\n                        \"tax\": {\n                            \"rate\": 0.00\n                        },\n                        \"type\": \"subscription_payment\",\n                        \"accountingCode\": \"customer_plan\"\n                    },\n                    {\n                        \"description\": \"Standard Master/Visa Fee\",\n                        \"amount\": {\n                            \"currency\": \"AUD\",\n                            \"value\": 1.24,\n                            \"type\": null\n                        },\n                        \"tax\": {\n                            \"rate\": 0.10\n                        },\n                        \"type\": \"transaction_fee\",\n                        \"accountingCode\": null\n                    }\n                ],\n                \"amount\": {\n                    \"currency\": \"AUD\",\n                    \"value\": 201.24,\n                    \"type\": null\n                },\n                \"totalTax\": {\n                    \"currency\": \"AUD\",\n                    \"value\": 0.00,\n                    \"type\": null\n                }\n            },\n            \"interval\": 1,\n            \"intervalUnit\": \"MONTH\",\n            \"totalPaid\": {\n                \"currency\": \"AUD\",\n                \"value\": 200.00,\n                \"type\": null\n            },\n            \"totalBillingCycles\": 1,\n            \"remainingToPay\": null,\n            \"remainingBillingCycles\": null,\n            \"endTargetAmount\": null,\n            \"endTargetBillingCycles\": null,\n            \"cancelledDate\": null,\n            \"failedPaymentHandling\": null,\n            \"failedAttemptsCount\": 0,\n            \"totalPastDue\": {\n                \"currency\": \"AUD\",\n                \"value\": 0.00,\n                \"type\": null\n            },\n            \"totalDiscounted\": {\n                \"currency\": \"AUD\",\n                \"value\": 0.00,\n                \"type\": null\n            },\n            \"metadata\": null,\n            \"createdOn\": \"2020-02-18T20:16:16.482\",\n            \"autoPayment\": true,\n            \"setupPayments\": null,\n            \"paymentMethodInvalidReason\": null,\n            \"paymentMethodInvalidDescription\": null,\n            \"paymentMethodInvalid\": false\n        }\n    ],\n    \"paging\": {\n        \"nextUrl\": null,\n        \"nextCursor\": 0,\n        \"limit\": 0,\n        \"totalCount\": 1\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "example": "9dc406b2-ec31-455d-9997-ccc9fae91064"
                          },
                          "customerId": {
                            "type": "string",
                            "example": "c68510ee-cbff-4f02-bc70-4e09b3197fca"
                          },
                          "planId": {
                            "type": "string",
                            "example": "c0ad2142-60e1-47e5-9d78-f6b5f1d09d19"
                          },
                          "name": {
                            "type": "string",
                            "example": "high_st_monthly_plan"
                          },
                          "status": {
                            "type": "string",
                            "example": "ACTIVE"
                          },
                          "startDate": {
                            "type": "string",
                            "example": "2020-02-19"
                          },
                          "endDate": {},
                          "paymentMethodToken": {
                            "type": "string",
                            "example": "5c4ab365-b000-48e6-b14c-eea9e97797f3"
                          },
                          "accountingCode": {
                            "type": "string",
                            "example": "customer_plan"
                          },
                          "amount": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string",
                                "example": "AUD"
                              },
                              "value": {
                                "type": "integer",
                                "example": 200,
                                "default": 0
                              },
                              "type": {}
                            }
                          },
                          "tax": {
                            "type": "object",
                            "properties": {
                              "rate": {
                                "type": "integer",
                                "example": 0,
                                "default": 0
                              }
                            }
                          },
                          "nextBillingDate": {
                            "type": "string",
                            "example": "2020-04-01"
                          },
                          "nextFutureInvoice": {
                            "type": "object",
                            "properties": {
                              "subscriptionId": {
                                "type": "string",
                                "example": "9dc406b2-ec31-455d-9997-ccc9fae91064"
                              },
                              "date": {
                                "type": "string",
                                "example": "2020-04-01"
                              },
                              "cycleStartDate": {
                                "type": "string",
                                "example": "2020-04-01"
                              },
                              "cycleEndDate": {
                                "type": "string",
                                "example": "2020-04-30"
                              },
                              "items": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "description": {
                                      "type": "string",
                                      "example": "high_st_monthly_plan"
                                    },
                                    "amount": {
                                      "type": "object",
                                      "properties": {
                                        "currency": {
                                          "type": "string",
                                          "example": "AUD"
                                        },
                                        "value": {
                                          "type": "integer",
                                          "example": 200,
                                          "default": 0
                                        },
                                        "type": {}
                                      }
                                    },
                                    "tax": {
                                      "type": "object",
                                      "properties": {
                                        "rate": {
                                          "type": "integer",
                                          "example": 0,
                                          "default": 0
                                        }
                                      }
                                    },
                                    "type": {
                                      "type": "string",
                                      "example": "subscription_payment"
                                    },
                                    "accountingCode": {
                                      "type": "string",
                                      "example": "customer_plan"
                                    }
                                  }
                                }
                              },
                              "amount": {
                                "type": "object",
                                "properties": {
                                  "currency": {
                                    "type": "string",
                                    "example": "AUD"
                                  },
                                  "value": {
                                    "type": "number",
                                    "example": 201.24,
                                    "default": 0
                                  },
                                  "type": {}
                                }
                              },
                              "totalTax": {
                                "type": "object",
                                "properties": {
                                  "currency": {
                                    "type": "string",
                                    "example": "AUD"
                                  },
                                  "value": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "type": {}
                                }
                              }
                            }
                          },
                          "interval": {
                            "type": "integer",
                            "example": 1,
                            "default": 0
                          },
                          "intervalUnit": {
                            "type": "string",
                            "example": "MONTH"
                          },
                          "totalPaid": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string",
                                "example": "AUD"
                              },
                              "value": {
                                "type": "integer",
                                "example": 200,
                                "default": 0
                              },
                              "type": {}
                            }
                          },
                          "totalBillingCycles": {
                            "type": "integer",
                            "example": 1,
                            "default": 0
                          },
                          "remainingToPay": {},
                          "remainingBillingCycles": {},
                          "endTargetAmount": {},
                          "endTargetBillingCycles": {},
                          "cancelledDate": {},
                          "failedPaymentHandling": {},
                          "failedAttemptsCount": {
                            "type": "integer",
                            "example": 0,
                            "default": 0
                          },
                          "totalPastDue": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string",
                                "example": "AUD"
                              },
                              "value": {
                                "type": "integer",
                                "example": 0,
                                "default": 0
                              },
                              "type": {}
                            }
                          },
                          "totalDiscounted": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string",
                                "example": "AUD"
                              },
                              "value": {
                                "type": "integer",
                                "example": 0,
                                "default": 0
                              },
                              "type": {}
                            }
                          },
                          "metadata": {},
                          "createdOn": {
                            "type": "string",
                            "example": "2020-02-18T20:16:16.482"
                          },
                          "autoPayment": {
                            "type": "boolean",
                            "example": true,
                            "default": true
                          },
                          "setupPayments": {},
                          "paymentMethodInvalidReason": {},
                          "paymentMethodInvalidDescription": {},
                          "paymentMethodInvalid": {
                            "type": "boolean",
                            "example": false,
                            "default": true
                          }
                        }
                      }
                    },
                    "paging": {
                      "type": "object",
                      "properties": {
                        "nextUrl": {},
                        "nextCursor": {
                          "type": "integer",
                          "example": 0,
                          "default": 0
                        },
                        "limit": {
                          "type": "integer",
                          "example": 0,
                          "default": 0
                        },
                        "totalCount": {
                          "type": "integer",
                          "example": 1,
                          "default": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"type\": \"api_error\",\n    \"code\": \"[customerId] [status] \",\n    \"message\": \"[At least one must have value.] [At least one must have value.] \"\n}"
                  },
                  "Invalid customerId format": {
                    "value": "{\n    \"type\": \"api_error\",\n    \"code\": \"[customerId]\",\n    \"message\": \"Value is invalid id format. Must be specified as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.\"\n}"
                  },
                  "Customer not found": {
                    "value": "{\n    \"type\": \"invalid_request_error\",\n    \"code\": \"customer_not_found\",\n    \"message\": \"Customer with specified customerId cannot be found.\"\n}"
                  },
                  "Invalid subscription status": {
                    "value": "{\n    \"type\": \"api_error\",\n    \"code\": \"[status] \",\n    \"message\": \"[Invalid status.] \"\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "api_error"
                        },
                        "code": {
                          "type": "string",
                          "example": "[customerId] [status] "
                        },
                        "message": {
                          "type": "string",
                          "example": "[At least one must have value.] [At least one must have value.] "
                        }
                      }
                    },
                    {
                      "title": "Invalid customerId format",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "api_error"
                        },
                        "code": {
                          "type": "string",
                          "example": "[customerId]"
                        },
                        "message": {
                          "type": "string",
                          "example": "Value is invalid id format. Must be specified as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX."
                        }
                      }
                    },
                    {
                      "title": "Customer not found",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "invalid_request_error"
                        },
                        "code": {
                          "type": "string",
                          "example": "customer_not_found"
                        },
                        "message": {
                          "type": "string",
                          "example": "Customer with specified customerId cannot be found."
                        }
                      }
                    },
                    {
                      "title": "Invalid subscription status",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "api_error"
                        },
                        "code": {
                          "type": "string",
                          "example": "[status] "
                        },
                        "message": {
                          "type": "string",
                          "example": "[Invalid status.] "
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```