LogoLogo
System Status
2021-03-23
2021-03-23
  • 2021-03-23
  • Charges
  • Checkouts
  • Country specifications
  • Customers
  • Events
  • Fees
  • File links
  • Files
  • Fulfillment cancellations
  • Fulfillment orders
  • Fulfillment returns
  • Fulfillments
  • Inventory items
  • Inventory levels
  • Invoices
  • Orders
  • Payouts
  • Plans
  • Refunds
  • Reservations
  • Returns
  • Sales summaries
  • Sales transactions
  • Shipments
  • Shipping quotes
  • SKUs
  • SKU groups
  • Sources
  • Subscriptions
  • Tax identifiers
  • Webhooks
Powered by GitBook
On this page

Plans

PreviousPayoutsNextRefunds

Last updated 5 months ago

The Plans resource defines the recurring billing behavior in subscriptions.

Gets a Plan by ID

get

Retrieves the details of a Plan.

Authorizations
Path parameters
idstringRequired

Plan identifier.

Responses
200
OK.
application/json
400
400 Bad Request
application/json
401
401 Unauthorized
application/json
403
403 Forbidden
application/json
404
404 Not Found
application/json
405
405 Method Not Allowed
application/json
406
406 Not Acceptable
application/json
408
408 Request Timeout
application/json
429
429 Too Many Requests
application/json
500
500 Internal Server Error
application/json
502
502 Bad Gateway Error
application/json
503
503 Service Unavailable Error
application/json
504
504 Gateway Timeout Error
application/json
get
GET /plans/{id} HTTP/1.1
Host: api.digitalriver.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "stateTransitions": {
    "activated": "2025-05-09T06:07:05.671Z",
    "activatedFree": "2025-05-09T06:07:05.671Z",
    "failed": "2025-05-09T06:07:05.671Z",
    "cancelled": "text",
    "ended": "text"
  },
  "updatedTime:": "2025-05-09T06:07:05.671Z",
  "liveMode": true,
  "id": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
  "terms": "These are the terms...",
  "contractBindingDays": 365,
  "interval": "month",
  "intervalCount": 1,
  "createdTime": "2025-05-09T06:07:05.671Z",
  "name": "Wireless keyboards",
  "reminderOffsetDays": 7,
  "billingOffsetDays": 4,
  "collectionPeriodDays": 10,
  "state": "active",
  "metadata": {
    "coupon": "iOS"
  }
}

Deletes a Plan by ID

delete

Permanently deletes a Plan. In the request, send the plan's unique identifier as a path parameter. Only plans in a draft can be deleted.

Authorizations
Path parameters
idstringRequired

Plan identifier

Responses
204
204 No Content
400
400 Bad Request
application/json
401
401 Unauthorized
application/json
403
403 Forbidden
application/json
404
401 Not Found
application/json
405
405 Method Not Allowed
application/json
406
406 Not Acceptable
application/json
408
408 Request Timeout
application/json
409
409 Conflict
application/json
429
429 Too Many Requests
application/json
500
500 Internal Server Error
application/json
502
502 Bad Gateway Error
application/json
503
503 Service Unavailable Error
application/json
504
504 Gateway Timeout Error
application/json
delete
DELETE /plans/{id} HTTP/1.1
Host: api.digitalriver.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

  • GETReturns a list of Plans
  • POSTCreates a Plan
  • GETGets a Plan by ID
  • POSTUpdates a Plan
  • DELETEDeletes a Plan by ID

Returns a list of Plans

get

Gets the Plans specified in the request.

Authorizations
Query parameters
statestringOptional

The state associated with the Plans you want to retrieve.

intervalstringOptional

The billing interval associated with the Plans you want to retrieve.

endingBeforestringOptional

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.

startingAfterstringOptional

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.

limitintegerOptional

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

Responses
200
200 OK
application/json
400
400 Bad Request
application/json
401
401 Unauthorized
application/json
403
403 Forbidden
application/json
405
405 Method Not Allowed
application/json
406
406 Not Acceptable
application/json
408
408 Request Timeout
application/json
429
429 Too Many Requests
application/json
500
500 Internal Server Error
application/json
502
502 Bad Gateway Error
application/json
503
503 Service Unavailable Error
application/json
504
504 Gateway Timeout Error
application/json
get
GET /plans HTTP/1.1
Host: api.digitalriver.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "hasMore": true,
  "data": [
    {
      "stateTransitions": {
        "activated": "2025-05-09T06:07:05.671Z",
        "activatedFree": "2025-05-09T06:07:05.671Z",
        "failed": "2025-05-09T06:07:05.671Z",
        "cancelled": "text",
        "ended": "text"
      },
      "updatedTime:": "2025-05-09T06:07:05.671Z",
      "liveMode": true,
      "id": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
      "terms": "These are the terms...",
      "contractBindingDays": 365,
      "interval": "month",
      "intervalCount": 1,
      "createdTime": "2025-05-09T06:07:05.671Z",
      "name": "Wireless keyboards",
      "reminderOffsetDays": 7,
      "billingOffsetDays": 4,
      "collectionPeriodDays": 10,
      "state": "active",
      "metadata": {
        "coupon": "iOS"
      }
    }
  ]
}

Creates a Plan

post

Submit this request to create a Plan.

Authorizations
Body
idstringOptional

The unique identifier of a Plan.

Example: 4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a
termsstringRequired

The contractual agreement displayed to the customer during the acquisition process.

Example: These are the terms...
contractBindingDaysintegerRequired

Indicates the agreed upon length of the contract. For example, an annual subscription should have a value of 365.

Example: 365
intervalstring · enumRequired

The supported billing intervals

Example: monthPossible values:
intervalCountintegerRequired

How often the customer is billed per the unit of time specified by interval (e.g. every 3 months).

Example: 1
namestring | nullableOptional

Describes the subscription products or services added to this plan.

Example: Womens cotton dresses
reminderOffsetDaysinteger | nullableOptional

The number of days before the opening of the invoice that the reminder event is triggered.

Example: 7
billingOffsetDaysinteger | nullableRequired

The number of days before the due date that billing is initiated.

Example: 4
collectionPeriodDaysinteger | nullableRequired

Represents the number of days that Digital River attempts to collect payment.

Example: 10
statestring · enumOptional

The valid states of a plan. Setting a plan to deactivated causes all connected subscriptions to end with the current period.

Example: activePossible values:
Responses
201
201 Created
application/json
400
400 Bad Request
application/json
401
401 Unauthorized
application/json
403
403 Forbidden
application/json
405
405 Method Not Allowed
application/json
406
406 Not Acceptable
application/json
408
408 Request Timeout
application/json
409
409 Conflict
application/json
429
429 Too Many Requests
application/json
500
500 Internal Server Error
application/json
502
502 Bad Gateway Error
application/json
503
503 Service Unavailable Error
application/json
504
504 Gateway Timeout Error
application/json
post
POST /plans HTTP/1.1
Host: api.digitalriver.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 288

{
  "id": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
  "terms": "These are the terms...",
  "contractBindingDays": 365,
  "interval": "month",
  "intervalCount": 1,
  "name": "Womens cotton dresses",
  "reminderOffsetDays": 7,
  "billingOffsetDays": 4,
  "collectionPeriodDays": 10,
  "state": "active",
  "metadata": {
    "coupon": "iOS"
  }
}
{
  "stateTransitions": {
    "activated": "2025-05-09T06:07:05.671Z",
    "activatedFree": "2025-05-09T06:07:05.671Z",
    "failed": "2025-05-09T06:07:05.671Z",
    "cancelled": "text",
    "ended": "text"
  },
  "updatedTime:": "2025-05-09T06:07:05.671Z",
  "liveMode": true,
  "id": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
  "terms": "These are the terms...",
  "contractBindingDays": 365,
  "interval": "month",
  "intervalCount": 1,
  "createdTime": "2025-05-09T06:07:05.671Z",
  "name": "Wireless keyboards",
  "reminderOffsetDays": 7,
  "billingOffsetDays": 4,
  "collectionPeriodDays": 10,
  "state": "active",
  "metadata": {
    "coupon": "iOS"
  }
}

Updates a Plan

post

Updates the specified Plan.

Authorizations
Path parameters
idstringRequired

The Plan identifier.

Body
namestring | nullableOptional

Describes the subscription products or services added to this plan.

Example: Wireless keyboards
reminderOffsetDaysinteger | nullableOptional

The number of days before the opening of the invoice that the reminder event is triggered.

Example: 7
billingOffsetDaysinteger | nullableRequired

The number of days before the due date that billing is initiated.

Example: 4
collectionPeriodDaysinteger | nullableRequired

Represents the number of days that Digital River attempts to collect payment.

Example: 10
statestring · enumOptional

The valid states of a plan. Setting a plan to deactivated causes all connected subscriptions to end with the current period.

Example: activePossible values:
Responses
200
200 OK
application/json
400
400 Bad Request
application/json
401
401 Unauthorized
application/json
403
403 Forbidden
application/json
404
401 Not Found
application/json
405
405 Method Not Allowed
application/json
406
406 Not Acceptable
application/json
408
408 Request Timeout
application/json
409
409 Conflict
application/json
429
429 Too Many Requests
application/json
500
500 Internal Server Error
application/json
502
502 Bad Gateway Error
application/json
503
503 Service Unavailable Error
application/json
504
504 Gateway Timeout Error
application/json
post
POST /plans/{id} HTTP/1.1
Host: api.digitalriver.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 145

{
  "name": "Wireless keyboards",
  "reminderOffsetDays": 7,
  "billingOffsetDays": 4,
  "collectionPeriodDays": 10,
  "state": "active",
  "metadata": {
    "coupon": "iOS"
  }
}
{
  "stateTransitions": {
    "activated": "2025-05-09T06:07:05.671Z",
    "activatedFree": "2025-05-09T06:07:05.671Z",
    "failed": "2025-05-09T06:07:05.671Z",
    "cancelled": "text",
    "ended": "text"
  },
  "updatedTime:": "2025-05-09T06:07:05.671Z",
  "liveMode": true,
  "id": "4a1a1fdd-2f7b-4a4e-92d2-2e843f06e82a",
  "terms": "These are the terms...",
  "contractBindingDays": 365,
  "interval": "month",
  "intervalCount": 1,
  "createdTime": "2025-05-09T06:07:05.671Z",
  "name": "Wireless keyboards",
  "reminderOffsetDays": 7,
  "billingOffsetDays": 4,
  "collectionPeriodDays": 10,
  "state": "active",
  "metadata": {
    "coupon": "iOS"
  }
}