> ## Documentation Index > Fetch the complete documentation index at: https://docs.staging.cope-demo.com/llms.txt > Use this file to discover all available pages before exploring further. # List subscriptions changed in a time window > Lists your subscriptions in the order their `updated_at` moved, oldest change first: the feed a reconciliation reads to learn what changed since it last looked. Every subscription whose `updated_at` is in the window `[updated_since, updated_until)` is returned exactly once, however many share one `updated_at` value. **Only changes at least 120 seconds old are served.** A change is stamped when it is written and becomes readable when it commits, so a window reaching up to now could pass a change that has not committed yet. `updated_until` defaults to now minus 120 seconds, may not be later, and is returned in the response. **Paging.** When `has_more` is true, request the next page with `starting_after` set to `next_cursor`. The cursor is opaque and carries the window and the filters of the first request, so the next page needs nothing else; a parameter repeated beside it must have the same value. Keep `limit` on every page. A subscription that changes while you page is not lost: its new `updated_at` is after the window, so the next window returns it. **A nightly sync.** Store the `updated_until` of the last walk you finished, and start the next one with `updated_since` set to it. The windows meet without overlapping, so nothing is missed and nothing is returned twice. **Reconcile without `status`.** `status` filters on the status a subscription has now, so a window filtered by it does not report a subscription that left that status (an `active` window does not show the one that was cancelled). Read the window unfiltered and filter on your side. Requires the `subscriptions` permission at `read`. An API key holds a permission at the lower of its own level (`read` for a read-only key) and its holder's role; a key without it is refused with 403. ## OpenAPI ````yaml /api-reference/commerce-v1.openapi.json get /v1/commerce/subscriptions openapi: 3.0.3 info: description: >- Public REST API for COPE vendor integrations. Authenticate with a COPE API key and call the endpoints described below. title: COPE Public API version: v1 servers: - description: Production url: https://api.cope.com security: - cope_sk: [] paths: /v1/commerce/subscriptions: get: tags: - Subscriptions summary: List subscriptions changed in a time window description: >- Lists your subscriptions in the order their `updated_at` moved, oldest change first: the feed a reconciliation reads to learn what changed since it last looked. Every subscription whose `updated_at` is in the window `[updated_since, updated_until)` is returned exactly once, however many share one `updated_at` value. **Only changes at least 120 seconds old are served.** A change is stamped when it is written and becomes readable when it commits, so a window reaching up to now could pass a change that has not committed yet. `updated_until` defaults to now minus 120 seconds, may not be later, and is returned in the response. **Paging.** When `has_more` is true, request the next page with `starting_after` set to `next_cursor`. The cursor is opaque and carries the window and the filters of the first request, so the next page needs nothing else; a parameter repeated beside it must have the same value. Keep `limit` on every page. A subscription that changes while you page is not lost: its new `updated_at` is after the window, so the next window returns it. **A nightly sync.** Store the `updated_until` of the last walk you finished, and start the next one with `updated_since` set to it. The windows meet without overlapping, so nothing is missed and nothing is returned twice. **Reconcile without `status`.** `status` filters on the status a subscription has now, so a window filtered by it does not report a subscription that left that status (an `active` window does not show the one that was cancelled). Read the window unfiltered and filter on your side. Requires the `subscriptions` permission at `read`. An API key holds a permission at the lower of its own level (`read` for a read-only key) and its holder's role; a key without it is refused with 403. operationId: commerce.subscriptions.list parameters: - description: >- Inclusive lower bound on `updated_at`, an RFC 3339 date-time with an offset or `Z`. Without it the window starts at the first subscription. in: query name: updated_since required: false schema: example: '2026-10-08T00:00:00.000Z' format: date-time type: string - description: >- Exclusive upper bound on `updated_at`, an RFC 3339 date-time with an offset or `Z`. Defaults to now minus 120 seconds; a later value is refused with 422. in: query name: updated_until required: false schema: example: '2026-10-09T00:00:00.000Z' format: date-time type: string - description: >- The `next_cursor` of the previous page. Opaque: it carries that request's window and filters, and a cursor this endpoint did not return is refused with 422. in: query name: starting_after required: false schema: type: string - description: >- Only subscriptions in this status now. A subscription that left this status in the window is not returned, so reconcile from the unfiltered window. in: query name: status required: false schema: enum: - pending - trial - active - overdue - paused - canceling - cancelled type: string - description: >- Only subscriptions sold on this product, by its `prod_` id. An id that is not one of your products is refused with 422 `validation_failed`. in: query name: product_id required: false schema: pattern: ^prod_[A-Za-z0-9]{8,32}$ type: string - description: How many subscriptions a page holds. in: query name: limit required: false schema: default: 25 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: schema: additionalProperties: false properties: data: items: additionalProperties: false properties: amount_minor_units: description: >- The recurring amount in force, in the minor units of `currency`. type: integer business: additionalProperties: false description: The business that sold the subscription. properties: id: example: biz_A1b2C3d4E5f6G7h8 pattern: ^biz_[A-Za-z0-9_-]{8,32}$ type: string object: enum: - business type: string required: - object - id type: object cancel_at: description: >- When the cancellation takes effect, or took effect. `null` when none was scheduled, and when it is not recorded. format: date-time nullable: true type: string cancelled_at: description: >- When the cancellation was accepted, or when the subscription ended for an ending nobody asked for. `null` when not cancelled, and when it is not recorded. format: date-time nullable: true type: string created_at: format: date-time type: string currency: type: string id: example: ps_A1b2C3d4E5f6 pattern: ^ps_[A-Za-z0-9]{8,32}$ type: string line_item: additionalProperties: false description: The order line it was sold on. properties: id: example: li_A1b2C3d4E5f6 pattern: ^li_[A-Za-z0-9]{8,32}$ type: string object: enum: - line_item type: string required: - object - id type: object next_billing_at: description: >- The next renewal. `null` while paused, once a cancellation has started, and while no renewal date is known. format: date-time nullable: true type: string object: enum: - subscription type: string order: additionalProperties: false description: >- The order it was sold in: `GET /v1/commerce/orders/{id}`. properties: id: example: ord_A1b2C3d4E5f6 pattern: ^ord_[A-Za-z0-9]{8,32}$ type: string object: enum: - order type: string required: - object - id type: object paused_at: description: '`null` unless `paused`.' format: date-time nullable: true type: string pending_change: additionalProperties: false description: >- A price or plan change waiting for the next renewal: present until a renewal bills its terms, on every payment method. `null` when none is waiting and once a cancellation has started. A renewal that bills nothing (a 100% discount) does not count, so the change stays pending until a paid renewal bills it. nullable: true properties: amount_minor_units: type: integer effective_at: description: >- The next renewal, which is when it takes effect. `null` while paused. format: date-time nullable: true type: string plan: additionalProperties: false properties: id: description: >- The id of the plan these terms were sold on or switched to. `null` when no recorded fact names the plan — for example, a subscription sold through an offer, a plan since deleted from the product, or one sold before plans were recorded. example: plan_A1b2C3d4 nullable: true pattern: ^plan_[A-Za-z0-9]{8,32}$ type: string interval: type: string interval_count: type: integer name: nullable: true type: string object: enum: - payment_plan type: string required: - object - id - name - interval - interval_count type: object type: enum: - price - plan type: string required: - type - amount_minor_units - plan - effective_at type: object plan: additionalProperties: false description: The plan in force for the period already billed. properties: id: description: >- The id of the plan these terms were sold on or switched to. `null` when no recorded fact names the plan — for example, a subscription sold through an offer, a plan since deleted from the product, or one sold before plans were recorded. example: plan_A1b2C3d4 nullable: true pattern: ^plan_[A-Za-z0-9]{8,32}$ type: string interval: type: string interval_count: type: integer name: nullable: true type: string object: enum: - payment_plan type: string required: - object - id - name - interval - interval_count type: object status: description: >- `canceling` means a cancellation was accepted and has not taken effect; it becomes `cancelled` when the subscription ends. enum: - pending - trial - active - overdue - paused - canceling - cancelled type: string updated_at: description: >- When the subscription last changed, in UTC to the millisecond. It moves whenever another field of this object changes, and can also move when none visibly did, for example after a change attempt that was refused. A change can become visible with an `updated_at` slightly earlier than the moment you read it (by up to the time a write takes to commit), and changes can share one value, so sync with `GET /v1/commerce/subscriptions`, which serves only changes old enough to have committed and pages through equal values, rather than by filtering on the last value you saw. format: date-time type: string required: - id - object - status - business - order - line_item - plan - amount_minor_units - currency - next_billing_at - paused_at - cancel_at - cancelled_at - created_at - updated_at - pending_change type: object type: array has_more: description: Whether another page follows this one. type: boolean next_cursor: description: >- Pass as `starting_after` for the next page. `null` when `has_more` is false. nullable: true type: string updated_until: description: >- The exclusive upper bound this walk serves, in UTC to the millisecond: the next window's `updated_since`. format: date-time type: string required: - data - has_more - next_cursor - updated_until type: object description: Successful response '400': content: application/problem+json: examples: unparsable_request: summary: Unparsable request value: code: invalid_request detail: >- The request could not be parsed. Check the query string and the request body. request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 400 title: Invalid Request type: https://docs.cope.com/errors/invalid_request schema: $ref: '#/components/schemas/PublicProblemDetail' description: Invalid request '401': content: application/problem+json: schema: $ref: '#/components/schemas/PublicProblemDetail' description: Missing or invalid bearer token '403': content: application/problem+json: schema: $ref: '#/components/schemas/PublicProblemDetail' description: Bearer token is not authorized for this route '422': content: application/problem+json: examples: validation_failed: summary: Validation failed value: code: validation_failed detail: null errors: - code: blank detail: Name can't be blank param: name request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 422 title: Validation Failed type: https://docs.cope.com/errors/validation_failed schema: $ref: '#/components/schemas/PublicProblemDetail' description: One or more query parameters failed validation '503': content: application/problem+json: examples: user_not_ready: summary: The key's user is not available yet value: code: user_not_ready detail: Retry after 2 seconds errors: - code: user_not_ready detail: Retry after 2 seconds request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 503 title: User Not Ready type: https://docs.cope.com/errors/user_not_ready tenant_not_ready: summary: The key's business is not available yet value: code: tenant_not_ready detail: Retry after 2 seconds errors: - code: tenant_not_ready detail: Retry after 2 seconds request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 503 title: Tenant Not Ready type: https://docs.cope.com/errors/tenant_not_ready schema: $ref: '#/components/schemas/PublicProblemDetail' description: >- The API key is valid but its user or business is not available to this API yet (`user_not_ready`, `tenant_not_ready`). Retry after the `Retry-After` seconds. security: - cope_sk: [] components: schemas: PublicProblemDetail: additionalProperties: false properties: code: type: string detail: nullable: true type: string errors: items: additionalProperties: false properties: code: type: string detail: type: string param: type: string required: - code - detail type: object type: array request_id: description: >- Correlates this response with COPE's logs; the response also carries it as `X-Request-Id`. It is the `X-Request-Id` you sent when that is 1-128 letters, digits, `_`, `@` or `-`, and otherwise one COPE generated. Quote it when you contact support. type: string status: type: integer title: type: string type: type: string required: - type - title - status - code - request_id type: object securitySchemes: cope_sk: description: >- Bearer credential for the public API: a live COPE API key (`ck_live_*`; keys issued earlier as `cope_sk_live_*` keep working). Dashboard sign-in tokens are not accepted. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.