Contact API support

Search recurring subscriptions

GET https://app.ecwid.com/api/v3/{storeId}/subscriptions

Request and response example

Request:

GET /api/v3/1003/subscriptions HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com

Response:

{
  "total": 10,
  "count": 5,
  "offset": 0,
  "limit": 100,
  "items": [
    {
      "subscriptionId": 66839,
      "customerId": 43343272,
      "status": "CANCELLED",
      "statusUpdated": "2021-07-23 21:17:26 +0000",
      "created": "2021-06-16 12:53:40 +0000",
      "cancelled": "2021-07-23 21:17:26 +0000",
      "nextCharge": "2021-07-16 12:53:40 +0000",
      "createTimestamp": 1623848020508,
      "updateTimestamp": 1627075046478,
      "chargeSettings": {
        "recurringInterval": "MONTH",
        "recurringIntervalCount": 1
      },
      "paymentMethod": {
        "creditCardMaskedNumber": "*1111",
        "creditCardBrand": "visa"
      },
      "orderTemplate": {
        "id": "121",
        "email": "[email protected]",
        "additionalInfo": {
          "creditCard": "*1111 (12/2024)",
          "creditCardExpirationMonth": "12",
          "creditCardExpirationYear": "2024",
          "google_customer_id": "11111111.2222222222",
          "stripeCardId": "pm_1X2xXXX34XXxXxxXxxxXXXX",
          "stripeCreditCardBrand": "visa",
          "stripeCreditCardLast4Digit": "1111",
          "stripeCustomerId": "cus_XXXxxxX12xxxxX",
          "stripeFingerprint": "xxxxxXXX1X2xxxXX",
          "stripeLiveMode": "false"
        },
        "orderComments": "",
        "paymentMethod": "Credit or debit card",
        "paymentModule": "Stripe",
        "total": 26.84,
        "subtotal": 12,
        "usdTotal": 32.545878290056045,
        "tax": 4.84,
        "customerTaxExempt": false,
        "customerTaxId": "",
        "customerTaxIdValid": false,
        "reversedTaxApplied": false,
        "items": [
          {
            "id": 762397105,
            "productId": 11111111,
            "categoryId": 0,
            "price": 12,
            "productPrice": 12,
            "shipping": 10,
            "tax": 4.84,
            "fixedShippingRate": 0,
            "sku": "006789",
            "name": "Mug",
            "shortDescription": "This is the best product in the world!",
            "quantity": 1,
            "quantityInStock": 37,
            "weight": 0.2,
            "trackQuantity": false,
            "fixedShippingRateOnly": false,
            "digital": false,
            "productAvailable": true,
            "imageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/11111/111111.jpg",
            "recurringChargeSettings": {
              "recurringInterval": "MONTH",
              "intervalCount": 1
            },
            "selectedOptions": [
              {
                "name": "Color",
                "type": "CHOICE",
                "value": "White",
                "valuesArray": [
                  "White"
                ],
                "selections": [
                  {
                    "selectionTitle": "White",
                    "selectionModifier": 0,
                    "selectionModifierType": "ABSOLUTE"
                  }
                ]
              }
            ],
            "taxes": [
              {
                "name": "VAT",
                "value": 22,
                "total": 4.84,
                "taxOnDiscountedSubtotal": 2.64,
                "taxOnShipping": 2.2,
                "includeInPrice": true
              }
            ],
            "dimensions": {
              "length": 21,
              "width": 21,
              "height": 21
            }
          }
        ],
        "billingPerson": {
          "name": "First Last",
          "companyName": "",
          "street": "Otto-Braun-Straße",
          "city": "Berlin",
          "countryCode": "DE",
          "countryName": "Germany",
          "postalCode": "10178",
          "stateOrProvinceCode": "BE",
          "stateOrProvinceName": "Berlin",
          "phone": "+491625555012"
        },
        "shippingPerson": {
          "name": "First Last",
          "companyName": "",
          "street": "Otto-Braun-Straße",
          "city": "Berlin",
          "countryCode": "DE",
          "countryName": "Germany",
          "postalCode": "10178",
          "stateOrProvinceCode": "BE",
          "stateOrProvinceName": "Berlin",
          "phone": "+11111111111"
        },
        "shippingOption": {
          "shippingMethodName": "Local delivery – City",
          "shippingRate": 10
        },
        "handlingFee": {},
        "pricesIncludeTax": false
      },
      "orders": [
        {
          "id": 266645518,
          "total": 26.84,
          "createDate": "2021-06-16 12:53:39 +0000"
        }
      ]
    }
  ]
}

Required access scopes

Your app must have the following access scopes to make this request: read_subscriptions

Path params

All path params are required.

Param
Type
Description

storeId

number

Ecwid store ID.

Query params

All query params are optional.

Name
Type
Description

id

number

Search term for the internal subscription ID.

createdFrom

string

Datetime when subscription was created (lower bound).

For example, 2024-05-26 13:37:46 +0000

createdTo

string

Datetime when subscription was created (upper bound).

For example, 2024-05-26 13:37:46 +0000

cancelledFrom

string

Datetime when subscription was cancelled (lower bound).

For example, 2024-05-26 13:37:46 +0000

cancelledTo

string

Datetime when subscription was cancelled (upper bound).

For example, 2024-05-26 13:37:46 +0000

updatedFrom

string

Datetime when subscription was updated for the last time (lower bound).

For example, 2024-05-26 13:37:46 +0000

updatedTo

string

Datetime when subscription was updated for the last time (upper bound).

For example, 2024-05-26 13:37:46 +0000

customerId

number

Search term for the internal customer ID.

status

string

Subscription status . One of: ACTIVE CANCELLED LAST_CHARGE_FAILED

REQUIRES_PAYMENT_CONFIRMATION

nextChargeFrom

string

Datetime of the next subscription charge (lower bound).

For example, 2024-05-26 13:37:46 +0000

nextChargeTo

string

Datetime of the next subscription charge (upper bound).

For example, 2024-05-26 13:37:46 +0000

recurringInterval

string

Search term for the time scale of subscription's recurring interval.

One of: DAY WEEK MONTH YEAR

recurringIntervalCount

number

Search term for the frequency of subscription's recurring charges. One of: for DAY - 1 (daily) for WEEK - 1 (weekly) or 2 (biweekly) for MONTH - 1 (monthly) or 3 (quarterly) for YEAR - 1 (annually)

productId

number

Search term for the ID of the subscription product.

email

string

Email of the customer who bought a subscription product.

orderId

string

Search term for the order ID with the subscription product inside.

orderTotal

number

Subscription's order total.

orderCreatedFrom

string

Datetime when the order with a subscription was placed (lower bound).

For example, 2024-05-26 13:37:46 +0000

orderCreatedTo

string

atetime when the order with a subscription was placed (upper bound).

For example, 2024-05-26 13:37:46 +0000

limit

number

Limit to the number of returned items. Maximum and default value (if not specified) is 100.

offset

number

Offset from the beginning of the returned items list. Used when the response contains more items than limit allows to receive in one request. Usually used to receive all items in several requests with multiple of a hundred, for example: ?offset=0 for the first request, ?offset=100, for the second request, ?offset=200, for the third request, etc.

sortBy

string

Sorting order for the response. One of: DATE_CREATED_ASC DATE_CREATED_DESC (default) ORDER_COUNT_ASC ORDER_COUNT_DESC NEXT_CHARGE_DATE_ASC NEXT_CHARGE_DATE_DESC

Headers

The Authorization header is required.

Header
Format
Description

Authorization

Bearer secret_ab***cd

Access token of the application.

Response JSON

A JSON object with the following fields:

Field
Type
Description

total

number

Total number of found items (might be more than the number of returned items).

count

number

Total number of items returned in the response.

offset

number

Offset from the beginning of the returned items list specified in the request.

limit

number

Maximum number of returned items specified in the request. Maximum and default value: 100.

items

array of objects items

Detailed information about returned subscriptions.

items

Field
Type
Description

subscriptionId

number

Internal subscription ID.

customerId

number

Internal ID of the customer who bought subscription.

status

string

One of: ACTIVE CANCELLED LAST_CHARGE_FAILED

REQUIRES_PAYMENT_CONFIRMATION

statusUpdated

string

Datetime when the subscription status was updated for the last time.

For example, 2024-05-26 13:37:46 +0000

created

string

Datetime when the order containing subscription was placed.

For example, 2024-05-26 13:37:46 +0000

cancelled

string

Datetime when the subscription was cancelled.

For example, 2024-05-26 13:37:46 +0000

nextCharge

string

Datetime of the next recurring charge for the subscription.

For example, 2024-05-26 13:37:46 +0000

createTimestamp

number

Datetime when the order containing subscription was placed in UNIX timestamp format.

For example, 1623848020508

updateTimestamp

number

Datetime when the subscription status was updated for the last time in UNIX timestamp format.

For example, 1623848020508

chargeSettings

object chargeSettings

Details about recurring charges set up for the subscription.

paymentMethod

object paymentMethod

Details about the payment method used for the subscription.

orders

object orders

Short details about the order containing the subscription: ID, total, creation date.

orderTemplate

object orderTemplate

Detailed information about the order containing the subscription.

chargeSettings

Field
Type
Description

recurringInterval

string

Search term for the time scale of subscription's recurring interval.

One of: DAY WEEK MONTH YEAR

recurringIntervalCount

number

Search term for the frequency of subscription's recurring charges. One of: for DAY - 1 (daily) for WEEK - 1 (weekly) or 2 (biweekly) for MONTH - 1 (monthly) or 3 (quarterly) for YEAR - 1 (annually)

paymentMethod

Field
Type
Description

creditCardMaskedNumber

string

Credit card masked number, e.g. *1111.

creditCardBrand

string

Credit card brand, e.g. Visa.

orders

Field
Type
Description

id

number

Internal order ID.

total

number

Order total .

createDate

string

Order creation date and time, e.g. 2021-06-16 12:53:39 +0000.

orderTemplate

A JSON object with the order details in the same format as in the GET order request.

PreviousRecurring subscriptionsNextGet recurring subscription

Last updated

Was this helpful?