Subscriptions

The Subscriptions resource is a key component in managing recurring billing for digital services or products. It allows businesses to automate payment processes, ensuring a seamless and consistent customer experience. By defining the details of a recurring subscription order, this resource helps in tracking and maintaining customer engagement through personalized and flexible billing cycles.

PreviousSources NextSubscription basics

Last updated 4 months ago

Returns a list of Subscriptions

Gets the Subscriptions specified in the request.

get

/subscriptions

Authorizations

Query parameters

planIdstring

The identifier of the plan associated with the subscriptions you want to retrieve.

statestring

The state associated with the subscriptions you want to retrieve.

customerIdstring

The identifer of the subscribing customer of the subscriptions you want to retrieve.

endingBeforestring

A cursor for use in pagination. The endingBefore parameter is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with xzy, your subsequent calls can include endingBefore=xzy in order to fetch the previous page of the list.

startingAfterstring

A cursor for use in pagination. The startingAfter parameter is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with xzy, your subsequent calls can include startingAfter=xzy in order to fetch the next page of the list.

limitinteger

A limit on the number of objects returned. Limit can range between 1 and 100, and the default is 10.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.digitalriver.com/subscriptions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

403

405

406

408

429

500

502

503

504

{
  "hasMore": true,
  "data": [
    {
      "contractBindingUntil": "2025-02-22T18:56:12.781Z",
      "createdTime": "2021-06-01T13:15:10.1077785Z",
      "updatedTime": "2021-06-01T13:17:10.1077788Z",
      "stateTransitions": {
        "activated": "2018-04-25T20:36:00Z",
        "activatedFree": "2018-04-25T20:36:00Z",
        "failed": "2018-04-25T20:36:00Z",
        "cancelled": "2018-04-25T20:36:00Z",
        "ended": "2018-04-25T20:36:00Z",
        "lapsed": "2018-04-25T20:36:00Z"
      },
      "liveMode": false,
      "id": "fb941eef-c3bb-42f8-bd47-f6da8bf6245d",
      "billingAgreementId": "24b217a7-79b5-4c84-8cae-34370646092f",
      "customerId": "exampleCustomerId",
      "sourceId": "exampleSourceId",
      "taxInclusive": true,
      "currency": "EUR",
      "planId": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
      "applicationId": "test",
      "locale": "de_DE",
      "currentPeriodStartDate": "2025-02-22T18:56:12.781Z",
      "currentPeriodEndDate": "2025-02-22T18:56:12.781Z",
      "nextInvoiceDate": "2021-07-02T13:15:10.0875833Z",
      "nextReminderDate": "2025-02-22T18:56:12.781Z",
      "metadata": {
        "coupon": "iOS"
      },
      "state": "active",
      "items": [
        {
          "aggregatePrice": 20,
          "price": 9.99,
          "metadata": {
            "coupon": "iOS"
          },
          "skuId": "1db7a3d6-1f4d-4d13-8ddc-ef4eccc6bd93",
          "productDetails": {
            "id": "100067660336",
            "skuGroupId": "wireless-keyboards",
            "name": "Keyboard",
            "description": "Top rated keyboard",
            "itemBreadcrumb": "Sports & Outdoors > Exercise & Fitness > Wearable Technology > Fitness Trackers",
            "url": "https://producturl.com",
            "countryOfOrigin": "US",
            "image": "https://imageurl.com",
            "weight": 20.5,
            "partNumber": "SWG1224J10L",
            "partnerAccountId": "00g6atnynbl2wFsFG357",
            "weightUnit": "oz"
          },
          "quantity": 1
        }
      ]
    }
  ]
}

200 OK

Gets a Subscription by ID

Retrieves the details of a Subscription.

get

/subscriptions/{id}

Authorizations

Path parameters

idstringrequired

Subscription identifier.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.digitalriver.com/subscriptions/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

401

403

404

405

406

408

429

500

502

503

504

{
  "contractBindingUntil": "2025-02-22T18:56:12.781Z",
  "createdTime": "2021-06-01T13:15:10.1077785Z",
  "updatedTime": "2021-06-01T13:17:10.1077788Z",
  "stateTransitions": {
    "activated": "2018-04-25T20:36:00Z",
    "activatedFree": "2018-04-25T20:36:00Z",
    "failed": "2018-04-25T20:36:00Z",
    "cancelled": "2018-04-25T20:36:00Z",
    "ended": "2018-04-25T20:36:00Z",
    "lapsed": "2018-04-25T20:36:00Z"
  },
  "liveMode": false,
  "id": "fb941eef-c3bb-42f8-bd47-f6da8bf6245d",
  "billingAgreementId": "24b217a7-79b5-4c84-8cae-34370646092f",
  "customerId": "exampleCustomerId",
  "sourceId": "exampleSourceId",
  "taxInclusive": true,
  "currency": "EUR",
  "planId": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
  "applicationId": "test",
  "locale": "de_DE",
  "currentPeriodStartDate": "2025-02-22T18:56:12.781Z",
  "currentPeriodEndDate": "2025-02-22T18:56:12.781Z",
  "nextInvoiceDate": "2021-07-02T13:15:10.0875833Z",
  "nextReminderDate": "2025-02-22T18:56:12.781Z",
  "metadata": {
    "coupon": "iOS"
  },
  "state": "active",
  "items": [
    {
      "aggregatePrice": 20,
      "price": 9.99,
      "metadata": {
        "coupon": "iOS"
      },
      "skuId": "1db7a3d6-1f4d-4d13-8ddc-ef4eccc6bd93",
      "productDetails": {
        "id": "100067660336",
        "skuGroupId": "wireless-keyboards",
        "name": "Keyboard",
        "description": "Top rated keyboard",
        "itemBreadcrumb": "Sports & Outdoors > Exercise & Fitness > Wearable Technology > Fitness Trackers",
        "url": "https://producturl.com",
        "countryOfOrigin": "US",
        "image": "https://imageurl.com",
        "weight": 20.5,
        "partNumber": "SWG1224J10L",
        "partnerAccountId": "00g6atnynbl2wFsFG357",
        "weightUnit": "oz"
      },
      "quantity": 1
    }
  ]
}

OK.

Updates the Subscription

Updates the specified Subscription

post

/subscriptions/{id}

Authorizations

Path parameters

idstringrequired

The Subscription identifier.

Body

planIdstringrequired

The Plan identifier.

Example: string

applicationIdstring | nullable

The identifier of the client application that created the subscription.

Example: test

localestring | nullable

A locale designator that combines the two-letter ISO 639-1 language code with a ISO 3166-1 alpha-2 country code.

Example: de_DE

sourceIdstring

The unique identifier of the subscription's reusable payment source.

Example: exampleSourceId

metadataMetadata

Key-value pairs used to store additional data. Value can be string, boolean or integer types.

Example: {"coupon":"iOS"}

statestring · enum

The state of the subscription

Example: active

Options: cancelled, active

itemsSubscriptionItems[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.digitalriver.com/subscriptions/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"planId":"string","applicationId":"test","locale":"de_DE","sourceId":"exampleSourceId","metadata":{"coupon":"iOS"},"state":"active","items":[{"aggregatePrice":20,"price":9.99,"metadata":{"coupon":"iOS"},"skuId":"1db7a3d6-1f4d-4d13-8ddc-ef4eccc6bd93","productDetails":{"id":"100067660336","skuGroupId":"wireless-keyboards","name":"Keyboard","description":"Top rated keyboard","itemBreadcrumb":"Sports & Outdoors > Exercise & Fitness > Wearable Technology > Fitness Trackers","url":"https://producturl.com","countryOfOrigin":"US","image":"https://imageurl.com","weight":20.5,"partNumber":"SWG1224J10L","partnerAccountId":"00g6atnynbl2wFsFG357","weightUnit":"oz"},"quantity":1}]}'

200

400

401

403

404

405

406

408

409

429

500

502

503

504

{
  "contractBindingUntil": "2025-02-22T18:56:12.781Z",
  "createdTime": "2021-06-01T13:15:10.1077785Z",
  "updatedTime": "2021-06-01T13:17:10.1077788Z",
  "stateTransitions": {
    "activated": "2018-04-25T20:36:00Z",
    "activatedFree": "2018-04-25T20:36:00Z",
    "failed": "2018-04-25T20:36:00Z",
    "cancelled": "2018-04-25T20:36:00Z",
    "ended": "2018-04-25T20:36:00Z",
    "lapsed": "2018-04-25T20:36:00Z"
  },
  "liveMode": false,
  "id": "fb941eef-c3bb-42f8-bd47-f6da8bf6245d",
  "billingAgreementId": "24b217a7-79b5-4c84-8cae-34370646092f",
  "customerId": "exampleCustomerId",
  "sourceId": "exampleSourceId",
  "taxInclusive": true,
  "currency": "EUR",
  "planId": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
  "applicationId": "test",
  "locale": "de_DE",
  "currentPeriodStartDate": "2025-02-22T18:56:12.781Z",
  "currentPeriodEndDate": "2025-02-22T18:56:12.781Z",
  "nextInvoiceDate": "2021-07-02T13:15:10.0875833Z",
  "nextReminderDate": "2025-02-22T18:56:12.781Z",
  "metadata": {
    "coupon": "iOS"
  },
  "state": "active",
  "items": [
    {
      "aggregatePrice": 20,
      "price": 9.99,
      "metadata": {
        "coupon": "iOS"
      },
      "skuId": "1db7a3d6-1f4d-4d13-8ddc-ef4eccc6bd93",
      "productDetails": {
        "id": "100067660336",
        "skuGroupId": "wireless-keyboards",
        "name": "Keyboard",
        "description": "Top rated keyboard",
        "itemBreadcrumb": "Sports & Outdoors > Exercise & Fitness > Wearable Technology > Fitness Trackers",
        "url": "https://producturl.com",
        "countryOfOrigin": "US",
        "image": "https://imageurl.com",
        "weight": 20.5,
        "partNumber": "SWG1224J10L",
        "partnerAccountId": "00g6atnynbl2wFsFG357",
        "weightUnit": "oz"
      },
      "quantity": 1
    }
  ]
}

200 OK

Deletes a Subscription by ID

Permanently deletes a subscription. Supply the unique identifier of the Subscription.

delete

/subscriptions/{id}

Authorizations

Path parameters

idstringrequired

Subscription identifier

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.digitalriver.com/subscriptions/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

400

401

403

404

405

406

408

409

429

500

502

503

504

No body

204 No Content