> For the complete documentation index, see [llms.txt](https://docs.2checkout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.2checkout.com/api-reference/reference/subscription-history.md).

# Subscription History

## Search the full change/audit history of a subscription

> Retrieve the history of a single subscription: changes, orders, notifications, deliveries and payment authorizations. It returns the same events as the History tab of the subscription page in the Merchant Control Panel.\
> \
> The date window (\`StartDate\`/\`EndDate\`) is optional and both bounds are inclusive. A date without a time means midnight, so send \`YYYY-MM-DD 23:59:59\` to include a whole last day. The result is filtered, not paginated: every event in the window is returned, newest first. If the range is too large to process in time, the request fails with \`HISTORY\_RANGE\_TOO\_LARGE\` (HTTP 422); retry with a narrower window.\
> \
> \`HistoryType\` applies to the \`CHANGE\` category only. New event types and new \`Details\` keys may be added over time, so handle unknown values gracefully. The response examples show every event type.\
> \
> This is distinct from \`GET /history/\`, which returns only renewals and delivery codes.

```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/history/search/":{"get":{"tags":["Subscription history"],"summary":"Search the full change/audit history of a subscription","description":"Retrieve the history of a single subscription: changes, orders, notifications, deliveries and payment authorizations. It returns the same events as the History tab of the subscription page in the Merchant Control Panel.\n\nThe date window (`StartDate`/`EndDate`) is optional and both bounds are inclusive. A date without a time means midnight, so send `YYYY-MM-DD 23:59:59` to include a whole last day. The result is filtered, not paginated: every event in the window is returned, newest first. If the range is too large to process in time, the request fails with `HISTORY_RANGE_TOO_LARGE` (HTTP 422); retry with a narrower window.\n\n`HistoryType` applies to the `CHANGE` category only. New event types and new `Details` keys may be added over time, so handle unknown values gracefully. The response examples show every event type.\n\nThis is distinct from `GET /history/`, which returns only renewals and delivery codes.","parameters":[{"name":"Accept","in":"header","required":true,"style":"simple","explode":false,"schema":{"type":"string","default":"application/json","enum":["application/json"]}},{"name":"X-Avangate-Authentication","in":"header","description":"Authentication header","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"SubscriptionReference","in":"path","description":"Unique, system-generated subscription identifier.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"StartDate","in":"query","description":"Start of the window, inclusive. Accepted formats: YYYY-MM-DD, YYYY-MM-DD HH:MM:SS (both in the merchant API timezone) or ISO-8601 with an optional UTC offset or Z. Relative expressions such as yesterday, and dates that do not exist, return INVALID_INPUT. Omit to leave the window open.","required":false,"schema":{"type":"string"}},{"name":"EndDate","in":"query","description":"End of the window, inclusive. Same formats as StartDate, and not earlier than StartDate (INVALID_DATE_RANGE). Omit to leave the window open.","required":false,"schema":{"type":"string"}},{"name":"Category","in":"query","description":"Filter by category, comma-separated (Category=CHANGE,ORDER) or repeated (Category[]=CHANGE). Values are case-insensitive; an unknown value returns INVALID_INPUT.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["CHANGE","ORDER","NOTIFICATION","DELIVERY","PAYMENT_AUTHORIZATION"]}}},{"name":"HistoryType","in":"query","description":"Filter by event type, comma-separated or repeated, for example EXTEND or DISABLE. Applies to CHANGE events only: when sent, only CHANGE events of these types are returned.","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionHistorySearchResult"}}}},"400":{"description":"Invalid data: StartDate after EndDate, a date not in an accepted format (YYYY-MM-DD, 'YYYY-MM-DD HH:MM:SS', or ISO-8601 with a UTC offset; relative expressions such as 'yesterday' are rejected) or one that does not exist on the calendar (e.g. 2026-02-30), an unknown Category, or a subscription reference that is unknown or not owned by the vendor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_400"}}}},"422":{"description":"The requested history range is too large to process within the allowed time. Narrow the date range and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_400"}}}}}}}},"components":{"schemas":{"SubscriptionHistorySearchResult":{"type":"object","properties":{"From":{"type":"string","description":"Applied window start (echoed), ISO-8601 in the merchant's configured API timezone (with UTC offset). Null when StartDate was omitted, i.e. no lower bound was applied."},"To":{"type":"string","description":"Applied window end (echoed), ISO-8601 in the merchant's configured API timezone (with UTC offset). Null when EndDate was omitted, i.e. no upper bound was applied."},"Items":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionHistoryEvent"}}}},"SubscriptionHistoryEvent":{"type":"object","properties":{"Type":{"type":"string","description":"Concrete event type (e.g. EXTEND, DISABLE, CHANGE_CUSTOM_PRICE, RENEWALS_AUTO, PAYMENT_AUTHORIZATION_ATTEMPT). The list may grow; handle unknown values gracefully."},"Category":{"type":"string","enum":["CHANGE","ORDER","NOTIFICATION","DELIVERY","PAYMENT_AUTHORIZATION"]},"Date":{"type":"string","description":"Event date, ISO-8601 in the merchant's configured API timezone (with UTC offset)."},"PerformedBy":{"type":"string","description":"Who performed the action, as a display string: the merchant company name (e.g. \"Merchant Inc.\"), \"partner \" + the partner company name (e.g. \"partner Reseller GmbH\"), \"customer \" + the customer full name (e.g. \"customer John Doe\"), \"2Checkout user\" for an action taken by 2Checkout staff on the account's behalf, or \"SYSTEM\" for automatic actions. Merchant and partner values get \" (via API)\" appended when the action came through the API."},"Details":{"type":"object","description":"Type-specific payload; always a JSON object ({} when the event carries no payload). Shape varies by Type: before/after changes use from/to objects keyed by the changed field name (a side with nothing recorded is omitted); ORDER events carry orderRef/product/toProduct; PAYMENT_AUTHORIZATION events carry successful/declineType (plus attemptNumber/transactionType/orderRef for order payments).","additionalProperties":true}}},"inline_response_400":{"type":"object","properties":{"error_code":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Retrieve the history of a subscription

> \*\*\*\
> \
> \*\*Overview\*\*\
> \
> Retrieve information on the evolution of a subscription in the 2Checkout system, including details of the initial acquisition and the subsequent renewals and upgrades.\
> \
> Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.

```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/history/":{"get":{"tags":["Subscription history"],"summary":"Retrieve the history of a subscription","description":"***\n\n**Overview**\n\nRetrieve information on the evolution of a subscription in the 2Checkout system, including details of the initial acquisition and the subsequent renewals and upgrades.\n\nSubscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.","parameters":[{"name":"Accept","in":"header","required":true,"style":"simple","explode":false,"schema":{"type":"string","default":"application/json","enum":["application/json"]}},{"name":"X-Avangate-Authentication","in":"header","description":"Authentication header","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"SubscriptionReference","in":"path","description":"Unique, system-generated subscription identifier.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}}}}}}}
```

## Extend a subscription

> Extends an existing subscription.

```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/history/":{"put":{"tags":["Subscription history"],"summary":"Extend a subscription","description":"Extends an existing subscription.","parameters":[{"name":"X-Avangate-Authentication","in":"header","description":"Authentication header","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":true,"style":"simple","explode":false,"schema":{"type":"string","enum":["application/json"]}},{"name":"SubscriptionReference","in":"path","description":"Unique, system-generated subscription identifier.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"Days","in":"query","description":"The number of days of delay.","required":true,"style":"form","explode":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_400"}}}}}}}},"components":{"schemas":{"inline_response_400":{"type":"object","properties":{"error_code":{"type":"string"},"message":{"type":"string"}}}}}}
```

## Retrieve a subscription's purchase, renewal or upgrade details

> Retrieve a snapshot of a subscription’s evolution corresponding to a specific purchase for which you provide the order reference number.

```json
{"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/subscriptions/{SubscriptionReference}/history/{OrderReference}/":{"get":{"tags":["Subscription history"],"summary":"Retrieve a subscription's purchase, renewal or upgrade details","description":"Retrieve a snapshot of a subscription’s evolution corresponding to a specific purchase for which you provide the order reference number.","parameters":[{"name":"Accept","in":"header","required":true,"style":"simple","explode":false,"schema":{"type":"string","default":"application/json","enum":["application/json"]}},{"name":"X-Avangate-Authentication","in":"header","description":"Authentication header","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"SubscriptionReference","in":"path","description":"Unique, system-generated subscription identifier.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"OrderReference","in":"path","description":"Reference number for approved/paid orders.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.2checkout.com/api-reference/reference/subscription-history.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
