Skip to main content
API docs by Redocly

Bold Subscriptions (1.0)

Download OpenAPI specification:Download

URL: https://developer-dashboard.boldcommerce.com/default/contactus Terms of Service

Bold Subscriptions customers use our API to interact with subscription data in unique ways. This includes the ability to modify, cancel, and report on subscriptions.

Refer to the changelog for the latest updates to this API.

For more information about Subscriptions, refer to the Overview.

Subscriptions

Contains information about subscriptions for your store and data associated with them. Use these endpoints to get, remove, edit, or list subscriptions.

List Subscriptions

Retrieve a list of subscriptions.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

query Parameters
subscription_status
any
Enum: "active" "inactive" "processing" "scheduled" "paused"
Example: subscription_status=active

Status of the subscriptions returned. Multiple statuses can be passed as an array.

bold_platform_customer_id
any
Example: bold_platform_customer_id=1

Customer Id of the subscriptions returned. Multiple customer ids can be passed as an array.

expand
string
Value: "customer"
Example: expand=customer

Fields to expand on the subscription. Multiple fields can be passed as an array

limit
integer
Example: limit=5

Maximum number of results to be returned

filter
string
Example: filter=?filter=lt(next_order_datetime:2021-11-15T00:00:00Z)+gt(next_order_datetime:2021-10-31T00:00:00Z)

Accepts filtering options as described on the Query & Pagination page. For example, to filter the next order date by a date interval, you could use the following parameter:

cursor
string
Example: cursor=?cursor= P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj

Returns the next page of results if supplied the next value from the previous pagination results.

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ],
  • "pagination": {
    }
}

Create Subscription

For more information about this endpoint, refer to Create Subscriptions.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Request Body schema: application/json
required
object
object

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Get Subscription

Retrieve a subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Update Subscription

Update a subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
object (SubscriptionEntity)
external_id
required
string or null
customer
required
any
next_order_datetime
required
string
next_payment_datetime
required
string
next_processing_datetime
required
string
subscription_status
required
string
Enum: "active" "inactive" "paused" "scheduled" "processing" "app_uninstalled" "waiting_sca_authorization"
payment_method_token
required
string
payment_gateway_public_id
required
string or null
payment_rrule
required
string
payment_rrule_text
required
string or null
order_rrule
required
string
order_rrule_text
required
string or null
last_payment_datetime
required
string or null
last_order_datetime
required
string or null
last_processed_datetime
required
string or null
current_retries
required
integer
charged_currency
required
string
base_to_charged_exchange_rate
required
integer
base_currency
required
string
object (CustomerAddressEntity)
object or null
idempotency_key
required
string
placed_at
string or null <data-time>
discount_code
required
string
billing_address_id
required
integer
shipping_address_id
required
integer
orders_processed
integer or null
last_failure_code
string or null
Enum: "alt_pp_payment_method_required" "bigcommerce_error" "card_declined" "card_expired" "credit_card_not_found" "discount_code_use_limit" "insufficient_funds" "invalid_billing_address" "invalid_bold_api_token" "invalid_card_expiration_month" "invalid_card_expiration_year" "invalid_card_number" "invalid_customer_email" "invalid_discount_code" "invalid_payment_method" "invalid_security_code" "invalid_shipping_address" "invalid_zip_code" "no_payment_provider" "payment_method_declined" "plugin_event_failed" "shopify_error" "stripe_support_required" "transaction_declined" "out_of_stock_product" "unaccepted_credit_card" "unknown_error" "unsupported_card" "unsupported_purchase_type" "unsupported_shipping_address" "woocommerce_error"

This code may help to identify the type of the error.

object or null

Default error messages for the last_failure_code field

last_failure_reason
string or null
Enum: "credit_card" "gateway" "cashier" "platform" "inventory" "other"

The reason for the failure

note
required
string or null

An internal-only note that you can add to a subscription. For a subscription recurrence, this note appears in the Additional Details section of the created order. Applicable for Shopify Checkout only.

order_note
required
string or null

A customer-facing note that you can add to a subscription. For the first order, this field retains the note added by the customer. For a subscription recurrence, this note appears in the Note section of the created order. Applicable for Shopify Checkout only.

order_count
integer

The number of orders created for the subscription.

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Partial Update Subscription

Partially update a subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
object (PartialUpdateSubscriptionEntity)
current_retries
integer
note
string or null

An internal-only note that you can add to a subscription. For a subscription recurrence, this note appears in the Additional Details section of the created order. Applicable for Shopify Checkout only.

order_note
string or null

A customer-facing note that you can add to a subscription. For the first order, this field retains the note added by the customer. For a subscription recurrence, this note appears in the Note section of the created order. Applicable for Shopify Checkout only.

order_count
integer

The number of orders created for the subscription.

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

List Subscription Intervals

Retrieve a list of available intervals for a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "intervals": [
    ]
}

Update Subscription Interval

Update the interval of a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_interval_id
required
integer

The subscription interval identifier.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Create Line Items

Add one or more line items to a subscription. Refer to Create Subscription Line Items for more information about the use cases of this endpoint.

Note: Adding line items to multi-currency subscriptions is not supported at this time.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
Array of objects
Array
platform_product_id
string

The ID of the product on your platform. Learn more about finding platform product IDs.

platform_variant_id
string

The ID of the product variant on your platform. All products, including those with no variants or a single variant, have a platform variant ID. Learn more about finding platform variant IDs.

quantity
integer

The quantity of this line item within the subscription.

price
integer

The price of this line item within the subscription, in the base unit (e.g., cents) of the charged_currency for this subscription. For example, a value of 1000 in a USD currency corresponds to a $10.00 USD per-unit price on the line item.

subscription_group_id
integer

The ID of the subscription group that contains the discount you want to add to this line item. Learn more about finding subscription group IDs.

Responses

Request samples

Content type
application/json
{
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "line_items": [
    ]
}

Reactivate Subscription

Reactivate an inactive or cancelled subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Cancel Subscription

Cancel a subscription and any future orders. Cancelled subscriptions will appear as 'inactive'.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Pause Subscription

Pause a subscription and any future orders. Paused orders will still appear as 'active'.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Subscription Groups

Contains information about subscription groups for your store, including shop ID and subscription group configuration. Use these endpoints to add, remove, edit, or list subscription groups.

List Selection Options

Retrieves a list of selection options. Selection options are the products available in a subscription group. Use this endpoint to view some or all selection options for the active subscription groups on a given store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

query Parameters
cursor
string
Example: cursor=?cursor=P2lkPTU1

A base 64 encoded cursor.

filter
string
Example: filter=?filter=in(platform_entity_id:1,2,3)

Accepts filtering options as described on the Query & Pagination page.

expand
string
Example: expand=?expand=subscription_group&expand=products

Fields to expand on the selection options. Currently accepts subscription_group and products

limit
integer
Example: limit=?limit=3L9

Limit the number of returned items.

latest
boolean
Default: false
Example: latest=true

If set to true, returns the most recent selection option for each distinct platform_entity_id in the response.

This is useful when using the expand=subscription_group query parameter by returning only the most recent subscription group a product was added to.

Responses

Response samples

Content type
application/json
{
  • "selection_options": [
    ],
  • "pagination": {
    }
}

List Subscription Groups

Retrieve a list of subscription groups.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Responses

Response samples

Content type
application/json
{
  • "subscription_groups": [
    ]
}

Create Subscription Group

Create a subscription group.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Request Body schema: application/json
required
object (SubscriptionGroupEntity)
internal_name
required
string
is_enabled
required
boolean
platform_id
required
string
allow_prepaid
required
boolean
is_prepaid_only
required
boolean
should_continue_prepaid
required
boolean
continue_prepaid_type
required
string
Enum: "as_prepaid" "as_standard"
allow_buffer_days
required
boolean
discount_type
required
string
Enum: "no_discount" "percentage" "fixed"
percent_discount
required
number
fixed_discount
required
integer
minimum_order_count_before_cancellable
required
integer
is_product_swappable
required
boolean
is_subscription_only
required
boolean
selection_type
required
string
Enum: "products" "collections"
group_type
required
string
Enum: "selectable" "fixed"
selectable_daily_allowed
required
boolean
selectable_weekly_allowed
required
boolean
selectable_yearly_allowed
required
boolean
selectable_max_interval_frequency
required
integer
fixed_interval_type
required
string
Enum: "daily" "weekly" "monthly" "yearly"
is_fixed_billing
required
boolean
can_add_to_cart
required
boolean
required
Array of objects (BillingRuleEntity)
required
Array of objects (SelectionOptionEntity)
required
Array of objects (PrepaidDuration)
Array of objects or null (DynamicDiscount)

Dynamic Discounts are applied when the provided number of orders are placed. All order numbers must be unique. Example: Base product price: $10.00 Initial discount: $1.00 Discounts: {"order_number": 2, "discount_type": "fixed", "discount_value": 250} {"order_number": 4, "discount_type": "percentage", "discount_value": 30} Line item prices will be: 1st order: $9.00 2nd order: $9.00 3rd order: $7.50 4th order: $7.50 5th order: $7.00

Responses

Request samples

Content type
application/json
{
  • "subscription_group": {
    }
}

Response samples

Content type
application/json
{
  • "subscription_group": {
    }
}

Get Subscription Group

Retrieve a subscription group by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

group_id
required
integer

The subscription group identifier.

Responses

Response samples

Content type
application/json
{
  • "subscription_group": {
    }
}

Update Subscription Group

Update a subscription group by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

group_id
required
integer

The subscription group identifier.

Request Body schema: application/json
required
object (SubscriptionGroupEntity)
internal_name
required
string
is_enabled
required
boolean
platform_id
required
string
allow_prepaid
required
boolean
is_prepaid_only
required
boolean
should_continue_prepaid
required
boolean
continue_prepaid_type
required
string
Enum: "as_prepaid" "as_standard"
allow_buffer_days
required
boolean
discount_type
required
string
Enum: "no_discount" "percentage" "fixed"
percent_discount
required
number
fixed_discount
required
integer
minimum_order_count_before_cancellable
required
integer
is_product_swappable
required
boolean
is_subscription_only
required
boolean
selection_type
required
string
Enum: "products" "collections"
group_type
required
string
Enum: "selectable" "fixed"
selectable_daily_allowed
required
boolean
selectable_weekly_allowed
required
boolean
selectable_yearly_allowed
required
boolean
selectable_max_interval_frequency
required
integer
fixed_interval_type
required
string
Enum: "daily" "weekly" "monthly" "yearly"
is_fixed_billing
required
boolean
can_add_to_cart
required
boolean
required
Array of objects (BillingRuleEntity)
required
Array of objects (SelectionOptionEntity)
required
Array of objects (PrepaidDuration)
Array of objects or null (DynamicDiscount)

Dynamic Discounts are applied when the provided number of orders are placed. All order numbers must be unique. Example: Base product price: $10.00 Initial discount: $1.00 Discounts: {"order_number": 2, "discount_type": "fixed", "discount_value": 250} {"order_number": 4, "discount_type": "percentage", "discount_value": 30} Line item prices will be: 1st order: $9.00 2nd order: $9.00 3rd order: $7.50 4th order: $7.50 5th order: $7.00

Responses

Request samples

Content type
application/json
{
  • "subscription_group": {
    }
}

Response samples

Content type
application/json
{
  • "subscription_group": {
    }
}

Delete Subscription Group

Delete a subscription group by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

group_id
required
integer

The subscription group identifier.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request",
  • "error_description": "The access token is missing"
}

Delete Selection Option by ID

Delete a selection option from inside a subscription group.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

group_id
required
integer

The subscription group identifier.

selection_option_id
required
string

Selection option ID of the item to be deleted from the group.

Responses

Delete Selection Option by Filter

Delete one or more selection options from inside a subscription group.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

group_id
required
integer

The subscription group identifier.

query Parameters
filter
required
string

Accepts filtering options as described here: https://developer.boldcommerce.com/guides/subscriptions-v2/resources/query-pagination. Example: to remove the platform product IDs 1, 2 and 3 from a subscription group, the following query param must be added: ?filter=in(platform_entity_id:1,2,3)

Responses

Add Selection Options by Platform Product ID(s)

Add one or more selection options from inside a subscription group.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

group_id
required
integer

The subscription group identifier.

Request Body schema: application/json

Add one or more selection options to a subscription group. Right now the only supported selection option is product. A list of platform product IDs can be passed as platform_entity_ids.

required
object
required
object
platform_entity_ids
required
Array of integers

These are product ids we are look

Responses

Request samples

Content type
application/json
{
  • "subscription_group": {
    }
}

Subscription Line Items

A child resource of Subscriptions. Contains information about line items in a subscription, including price, details, and swappable products. Use these endpoints to get, remove, edit, or list line items for subscriptions.

Swap Line Items

Swap line item products on a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
Array of objects (SwapProductEntity)
Array
line_item_id
integer
platform_product_id
string
platform_variant_id
string
subscription_group_id
integer

Responses

Request samples

Content type
application/json
{
  • "swap_products": [
    ]
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Update Line Items

Update the line items of a subscription. Refer to Manage Subscription Line Items for more information about the use cases of this endpoint.

When updating the price of the line item, change the price field in the request body. This value must be in the charged_currency of the subscription, and it must be in the base currency unit (i.e., cents). This price is the final output price of the line item on this order; any applicable subscription group discounts or price changes will not be applied.

Example: If you include price: 4000 in the request body, the line item price is set to $40.00 CAD for all upcoming orders.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
object
Array of objects (PatchLineItemEntity)
Array
id
required
integer or null

Read-only.

Line item identifier.

subscription_id
required
integer or null

Read-only.

Subscription identifier.

platform_id
required
string

Read-only.

Identifier from the platform.

platform_product_id
required
string or null

Read-only.

Product identifier from the platform.

platform_variant_id
required
string or null

Read-only.

Variant identifier from the platform.

subscription_group_id
required
integer

Subscription group identifier.

subscription_group_billing_rules_id
required
integer or null

Billing rules identifier for the subscription group.

title
required
string

Line item title.

product_name
required
string or null

Read-only.

Product name.

variant_name
required
string or null

Read-only.

Variant name.

sku
required
string

Product SKU.

url
required
string

Read-only.

Product URL.

image
required
string

Product image.

quantity
required
integer

Product quantity.

price
integer or null

Product price. If changed, all related price fields may be impacted. If omitted, the price will be used from the exising line item when updating or the matching product when adding a new line item.

price_charged
required
integer or null

Read-only.

Influenced by changes made to the price field.

discounted_price
required
integer

Read-only.

Influenced by changes made to the price field.

discounted_price_charged
required
integer

Read-only.

Influenced by changes made to the price field.

full_price
required
integer

Read-only.

Influenced by changes made to the price field.

full_price_charged
integer

Read-only.

Influenced by changes made to the price field.

requires_shipping
required
boolean

Whether or not the line item requires shipping.

grams
required
integer

Product weight in grams.

weight
required
number

Product weight in weight_unit.

weight_unit
required
string

Unit used for weight.

taxable
required
boolean

Whether or not the line item is taxable.

required
Array of objects (LineItemDiscountEntity)

Read-only.

All discounts associated with the line item.

prepaid_metadata
required
object or null
Value: null

Read-only.

Prepaid properties, as defined in the Create Line Item Prepaid Metadata and Update Line Item Prepaid Metadata endpoint. Set to null when using the Update Subscription Line Items endpoint.

Array of objects (LineItemAttributeEntity)

Read-only.

Additional attributes associated with the line item.

Use the Update Line Item Attributes endpoint to add, update, or delete line item attributes.

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Delete Line Item

Delete a line item from a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Get Line Item

Retrieve the details of a specific line item from a given subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

Responses

Response samples

Content type
application/json
{
  • "subscription_line_item": {
    }
}

List Swappable Products by Line Item

Retrieve a list of swappable products for a subscription line item.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

query Parameters
limit
integer

Maximum number of results to be returned

page
integer

The desired page number for the paginated result

Responses

Response samples

Content type
application/json
{}

Create Line Item Attributes

Add a new set of attributes to a line item.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

Request Body schema: application/json
Array of objects (LineItemAttributeEntity)
Array
name
string

The name of the custom field/attribute, up to 250 characters.

value
string

The content of the custom field/attribute.

Responses

Request samples

Content type
application/json
{
  • "line_item_attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "line_item_attributes": [
    ]
}

Update Line Item Attributes

Create, remove, or update attributes for a specific line item inside a subscription. Your request payload must contain the full list of attributes for the line item.

To add an attribute to the line item, include a new attribute in the request payload. To update an attribute that already exists on the line item, include the attribute in the payload with the same name and an updated value. To delete one attribute, leave the attribute out of the request payload. To remove all attributes of a line item, use an empty array as the request payload.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

Request Body schema: application/json
Array of objects (LineItemAttributeEntity)
Array
name
string

The name of the custom field/attribute, up to 250 characters.

value
string

The content of the custom field/attribute.

Responses

Request samples

Content type
application/json
{
  • "line_item_attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "subscription_line_item": {
    }
}

Create Line Item Prepaid Metadata

Add prepaid metadata to a line item to convert a subscription to prepaid. Adding this metadata to one line item converts the whole order to prepaid.

Note: Converting a subscription to prepaid does not automatically charge the customer for the balance of the prepaid subscription. To charge the customer the prepaid subscription amount on the next recurrence, set prepaid_duration to the same value as prepaid_recurrence_count, and set prepaid_continue to as_prepaid. This causes Bold to start a new prepaid subscription on the next recurrence and set the prepaid_recurrence_count back to 1.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

Request Body schema: application/json
object (PrepaidMetadataEntity)
id
integer

The ID of the prepaid metadata.

line_item_id
integer

The ID of the subscription line item this prepaid metadata belongs to.

prepaid_continue
required
string
Enum: "no_continue" "as_prepaid" "as_standard"

The behavior of the subscription once the number of recurrences has reached the prepaid_duration.

  • no_continue: The subscription will be cancelled.
  • as_prepaid : The customer will be charged for new set of order recurrences on the next recurrence.
  • as_standard: The subscription will be converted to a standard subscription, where the customer is charged for one order at each recurrence.
prepaid_duration
required
integer

The number of subscription recurrences that have been prepaid.

current_recurrence_count
required
integer

The number of subscription recurrences that have occurred.

Responses

Request samples

Content type
application/json
{
  • "prepaid_metadata": {
    }
}

Response samples

Content type
application/json
{
  • "prepaid_metadata": {
    }
}

Update Line Item Prepaid Metadata

Update or create new prepaid metadata for a line item.

Note: Updating the prepaid_duration or current_recurrence_count does not result in any automatic charges or change in charges to an existing prepaid customer. Adding new prepaid metadata to a subscription converts it to prepaid. For more information on converting a subscription to prepaid, refer to the Create Line Item Prepaid Metadata endpoint.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

line_item_id
required
integer

Line item ID to view and manage data for.

Request Body schema: application/json
object (PrepaidMetadataEntity)
id
integer

The ID of the prepaid metadata.

line_item_id
integer

The ID of the subscription line item this prepaid metadata belongs to.

prepaid_continue
required
string
Enum: "no_continue" "as_prepaid" "as_standard"

The behavior of the subscription once the number of recurrences has reached the prepaid_duration.

  • no_continue: The subscription will be cancelled.
  • as_prepaid : The customer will be charged for new set of order recurrences on the next recurrence.
  • as_standard: The subscription will be converted to a standard subscription, where the customer is charged for one order at each recurrence.
prepaid_duration
required
integer

The number of subscription recurrences that have been prepaid.

current_recurrence_count
required
integer

The number of subscription recurrences that have occurred.

Responses

Request samples

Content type
application/json
{
  • "prepaid_metadata": {
    }
}

Response samples

Content type
application/json
{
  • "prepaid_metadata": {
    }
}

Subscription Orders

A child resource of Subscriptions. Contains information about orders in a subscription, including schedules, order histories, and current orders. Use these endpoints to list, get, skip, or unskip orders.

List Orders

Retrieve a list of subscription orders for a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

query Parameters
page
integer

The desired page number for the paginated result

limit
integer

Maximum number of results to be returned

Responses

Response samples

Content type
application/json
{
  • "subscription_orders": [
    ]
}

Get Order

Retrieve a subscription order for a subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

order_id
required
integer

The order identifier.

Responses

Response samples

Content type
application/json
{
  • "id": 1008130,
  • "subscription_id": 316561,
  • "shop_id": 6481,
  • "base_to_charged_exchange_rate": 1,
  • "base_currency": "CAD",
  • "order": {
    },
  • "is_multi_currency": true,
  • "created_at": "2021-07-09T18:13:40Z",
  • "updated_at": "2021-07-09T18:13:40Z"
}

Update Next Order Datetime

Update the datetime of the next subscription order in RFC 3339 format.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
nextDate
string
includeFutureOrders
boolean
Default: false

Also adjust the order datetimes of all future orders to match the new next order date with the old interval.

Responses

Request samples

Content type
application/json
{
  • "nextDate": "2020-01-20T18:00:00Z",
  • "includeFutureOrders": false
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Unskip Previously Skipped Order

Restore a previously skipped future subscription order. Specify the date of the order to be unskipped.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
date
string

The date of the previously skipped order (to be restored/unskipped)

Responses

Request samples

Content type
application/json
{
  • "date": "2020-01-20T18:00:00Z"
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Skip Subscription Order

Skip a subscription's upcoming order by date.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
date
string

Responses

Request samples

Content type
application/json
{
  • "date": "2020-01-20T18:00:00Z"
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Subscription Adjustments

A child resource of Subscriptions. Contains information about future adjustments to a subscription or its orders. Use these endpoints to create, list, or delete adjustments for a subscription.

Create Subscription Adjustments

Creates adjustments for a subscription or its orders.

For more information on subscription adjustments, refer to the Adjust Subscription Orders guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
Array of objects (SubscriptionAdjustment)
Array
name
string

The name of the adjustment.

description
string

The description of the adjustment being made to the subscription or its orders.

target
string
Enum: "subscription" "order"

The target of the adjustment.

SubscriptionAdjustmentTriggerOrderCount (object) or SubscriptionAdjustmentTriggerOrderDatetime (object)

The condition for when and how often the action will be made against the target.

SubscriptionAdjustmentActionAddLineItem (object) or SubscriptionAdjustmentActionUpdateLineItemQuantity (object) or SubscriptionAdjustmentActionApplyPrice (object)

The action that should be made against the target of the adjustment.

Responses

Request samples

Content type
application/json
Example
{
  • "adjustments": [
    ]
}

Response samples

Content type
application/json
{
  • "adjustments": [
    ]
}

List Subscription Adjustments

Lists adjustments for a subscription or its orders.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

query Parameters
filter
string

Accepts filtering options as described in Query & Pagination. For example, to limit the request to all future adjustments to individual orders, the following query param may be added: ?filter=eq(target:order)

Responses

Response samples

Content type
application/json
{
  • "adjustments": [
    ]
}

Delete Subscription Adjustments

Deletes adjustments for a subscription or its orders.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

query Parameters
filter
string

Accepts filtering options as described in Query & Pagination. For example, to limit the request to all future adjustments to individual orders, the following query param may be added: ?filter=eq(target:order)

Responses

Response samples

Content type
application/json
[ ]

Get Subscription Adjustment by ID

Gets an adjustment by its ID.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

adjustment_id
required
integer

The subscription adjustment identifier.

Responses

Response samples

Content type
application/json
{
  • "adjustment": {
    }
}

Delete Subscription Adjustment by ID

Deletes an adjustment by its ID.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

adjustment_id
required
integer

The subscription adjustment identifier.

Responses

Response samples

Content type
application/json
[ ]

Future Orders

Contains information about future orders for subscriptions. Use these endpoints to list future orders for a shop or individual subscriptions.

List Future Orders

Lists future subscription orders for the shop.

For more information, refer to the View Future Orders guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

query Parameters
limit
integer
Default: 50
Example: limit=10

The maximum number of results to be returned.

filter
string
Example: filter=lte(order_datetime:2024-05-10T23:59:59)

Filter future orders. Accepts filtering options as described in the Query and Pagination reference.

subscription_filter
string
Example: subscription_filter=eq(bold_customer_id:3623267)

Filter future orders. Accepts filtering options as described in the Query and Pagination reference.

To see available filters, refer to the Future Orders guide.

cursor
string
Example: cursor=P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj

A Base-64 encoded cursor. Used to get a page of data on a cursor paginated request. Obtained from the response of a previous request.

Responses

Response samples

Content type
application/json
{
  • "future_orders": [
    ],
  • "pagination": {
    }
}

List Future Orders by Subscription ID

Lists future orders for a subscription.

For more information, refer to the View Future Orders guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

query Parameters
limit
integer
Default: 50
Example: limit=10

The maximum number of results to be returned.

filter
string
Example: filter=lte(order_datetime:2024-05-10T23:59:59)

Filter future orders. Accepts filtering options as described in the Query and Pagination reference.

cursor
string
Example: cursor=P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj

A Base-64 encoded cursor. Used to get a page of data on a cursor paginated request. Obtained from the response of a previous request.

Responses

Response samples

Content type
application/json
{
  • "future_orders": [
    ],
  • "pagination": {
    }
}

Convertible Adjustments

Use these endpoints to create, update, or delete convertible adjustment plans, enabling automatic product conversions on subscription line items attached to a created plan.

Create Convertible Adjustment Group

Creates a convertible adjustment group for a store. When created, the adjustment group does not have any products associated with it. Convertible adjustments enable customers to convert their subscription after an initial order.

For example, if the initial subscription order included a coffee maker and coffee grounds, a convertible adjustment allows subsequent orders to contain only coffee grounds.

After calling this endpoint, call Create Convertible Adjustment Group Items to attach the created convertible adjustment group items to the adjustment group.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Request Body schema: application/json
required
required
object
required
object (ConvertibleAdjustmentGroup)
on_cycle_end
required
string
Enum: "repeat_cycle" "continue_last_item" "remove_from_subscription"
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create Convertible Adjustment Group Items

Creates convertible adjustment group items used for a selection option. The first item in the items array represents the initial product and the second item represents the product it will convert to after the initial order is placed.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

adjustment_id
required
integer

The convertible adjustment group identifier, obtained from calling Create Convertible Adjustment Group.

Request Body schema: application/json
required
required
object
required
Array of objects (ConvertibleAdjustmentGroupItemEntity) >= 2 items unique
Array (>= 2 items)
type
required
string
Enum: "product" "initial_product"
object or null (ConvertibleAdjustmentGroupItemProduct)
discount_value
integer
discount_type
required
string
Enum: "percentage" "fixed" "no_discount"

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Convertible Adjustment Group Items

Deletes all convertible adjustment group items from a convertible adjustment group.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

adjustment_id
required
integer

The convertible adjustment group identifier, obtained from calling Create Convertible Adjustment Group.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Convertible Adjustment Group

Deletes a convertible adjustment group and its items for a store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

adjustment_id
required
integer

The convertible adjustment group identifier, obtained from calling Create Convertible Adjustment Group.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Convertible Adjustment Group

Updates a convertible adjustment group for a store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

adjustment_id
required
integer

The convertible adjustment group identifier, obtained from calling Create Convertible Adjustment Group.

Request Body schema: application/json
required
required
object
required
object (ConvertibleAdjustmentGroup)
on_cycle_end
required
string
Enum: "repeat_cycle" "continue_last_item" "remove_from_subscription"
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Convertible Adjustment Group Item

Deletes a convertible adjustment group item from a convertible adjustment group using the convertible adjustment group item ID

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

adjustment_id
required
integer

The convertible adjustment group identifier, obtained from calling Create Convertible Adjustment Group.

adjustment_item_id
required
integer

The convertible adjustment group item identifier, obtained from calling Create Convertible Adjustment Group Items.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Convertible Adjustment Group Item

Updates a convertible adjustment group item from a convertible adjustment group using the convertible adjustment group item ID

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

adjustment_id
required
integer

The convertible adjustment group identifier, obtained from calling Create Convertible Adjustment Group.

adjustment_item_id
required
integer

The convertible adjustment group item identifier, obtained from calling Create Convertible Adjustment Group Items.

Request Body schema: application/json
required
required
object
required
object (ConvertibleAdjustmentGroupItemEntity)
type
required
string
Enum: "product" "initial_product"
object or null (ConvertibleAdjustmentGroupItemProduct)
discount_value
integer
discount_type
required
string
Enum: "percentage" "fixed" "no_discount"

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Customers

A child resource of Subscriptions. Contains information about customers for a subscription. Use these endpoints to manage customer data for a specific subscription.

List Customers

Retrieve a list of customers.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

query Parameters
search
string
Examples:
  • search=#1234 - By subscription ID
  • search=123456 - By phone

Search with a specific target. It's possible to search by subscription ID or phone number.

status
string
Default: "all"
Enum: "all" "active" "inactive"
Example: status=active

Customer status to filter.

limit
integer
Default: 50
Example: limit=10

The maximum number of results to be returned.

page
integer
Default: 1
Example: page=2

The page to request.

Responses

Response samples

Content type
application/json
{
  • "customers": [
    ]
}

Get Customer

Retrieve a customer by their id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

Responses

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Update Customer

Update a customer by their id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

Request Body schema: application/json
required
object (CustomerEntity)
first_name
required
string

The customer's first name.

last_name
required
string

The customer's last name.

email
required
string

The customer's email

phone
required
string

The customer's phone number. For Shopify checkout users, you can configure phone number requirements in the admin.

notes
required
string

The customer's internal notes. This is applied as a note in the Customer info section of Bold Subscriptions admin.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

List Customer Addresses

Retrieve a list of addresses for a customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

Responses

Response samples

Content type
application/json
{
  • "customer_addresses": [
    ]
}

Create Customer Address

Create an address for a customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

Request Body schema: application/json
required
object (UpdateCustomerAddressEntity)
first_name
required
string

Customer's first name.

last_name
required
string

Customer's last name(s).

company
string

Customer's company name.

phone
required
string

Customer's phone number.

street1
required
string

Customer's street address (street name and number).

street2
string

Address complement (suite number, unit number, etc.).

city
required
string

Customer's city.

province
required
string

Customer's province or state, as applicable. Can be an empty string in case the address has no state/province.

province_code
required
string

Customer's province or state code (usually 2 characters), as applicable. If the address has no state/province, leave empty.

country
required
string

Customer's country name.

country_code
required
string

Customer's alpha 2 country code, according to ISO 3166-1 (reference: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

zip
required
string

Customer's postal code.

is_default
boolean

Indicates whether this address should be considered the default one for the customer.

address_use
string

Address usage (billing, shipping). Only set for WooCommerce.

Responses

Request samples

Content type
application/json
{
  • "customer_address": {
    }
}

Response samples

Content type
application/json
{
  • "customer_address": {
    }
}

Update Customer Address

Update an address for a customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

address_id
required
integer

The address identifier.

Request Body schema: application/json
required
object (UpdateCustomerAddressEntity)
first_name
required
string

Customer's first name.

last_name
required
string

Customer's last name(s).

company
string

Customer's company name.

phone
required
string

Customer's phone number.

street1
required
string

Customer's street address (street name and number).

street2
string

Address complement (suite number, unit number, etc.).

city
required
string

Customer's city.

province
required
string

Customer's province or state, as applicable. Can be an empty string in case the address has no state/province.

province_code
required
string

Customer's province or state code (usually 2 characters), as applicable. If the address has no state/province, leave empty.

country
required
string

Customer's country name.

country_code
required
string

Customer's alpha 2 country code, according to ISO 3166-1 (reference: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

zip
required
string

Customer's postal code.

is_default
boolean

Indicates whether this address should be considered the default one for the customer.

address_use
string

Address usage (billing, shipping). Only set for WooCommerce.

Responses

Request samples

Content type
application/json
{
  • "customer_address": {
    }
}

Response samples

Content type
application/json
{
  • "customer_address": {
    }
}

Delete Customer Address

Delete an address from a customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

address_id
required
integer

The address identifier.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request",
  • "error_description": "The access token is missing"
}

List Customer Subscriptions

Retrieve a list of subscriptions for a single customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

customer_id
required
integer
Example: 12

The customer identifier.

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ],
  • "pagination": {
    }
}

Payment Methods

A child resource of Subscriptions. Contains information about payment methods for subscriptions, including public payment IDs, alternate payment methods, and available methods. Use these endpoints to get, remove, edit, and list payment methods associated with a subscription.

Get Payment Method

Retrieve the current payment method information of a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "payment_method": {
    }
}

Trigger Update Payment Method Email

Note: Available for Shopify Checkout only.

Trigger an email to the customer that allows them to update their payment method for the subscription. This endpoint can only be called if the subscription's payment method has an update_method of trigger_email.

You can change the contents of the email in Shopify's "Customer payment method update request" email settings.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{ }

List Payment Methods

Retrieve a list of available payment methods for a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "payment_methods": [
    ]
}

List Alternative Payment Methods

Retrieve a list of alternative payment methods for a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "gift_card": [
    ]
}

Create Alternative Payment Method

Add an alternate payment method to a subscription.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

Request Body schema: application/json
required
Array of objects = 1 items unique
Array (= 1 items)
type
required
string non-empty
object

Responses

Request samples

Content type
application/json
Example
{
  • "alternative_payment_methods": [
    ]
}

Response samples

Content type
application/json
{
  • "alternative_payment_methods": [
    ]
}

Delete Alternative Payment Method

Remove an alternative payment method from a subscription its paymentPublicID.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

subscription_id
required
integer

The subscription identifier.

payment_public_id
required
string

Responses

Shops

Contains information about your store, including store IDs, domains, platform, and admin configuration. Use these endpoints to manage store information and settings.

Get Shop Info

Retrieve basic information about a shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Responses

Response samples

Content type
application/json
{
  • "shop": {
    }
}

Webhook Events

Contains information about webhook events, including webhook event ID, attempts, and webhook event metadata. Use these endpoints to get webhook event information.

List Webhook Events

Retrieve a list of webhook events.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

query Parameters
since_id
integer
limit
string

Maximum number of results to be returned

filters
Array of strings
Items Enum: "shop_id" "webhook_subscription_id" "webhook_topic_id" "uuid" "attempts" "last_response_status_code" "id" "created_at" "updated_at" "delivered_at"

Filter event webhooks. Mulitple filters can be passed in the array.

Responses

Response samples

Content type
application/json
{
  • "webhook_events": [
    ],
  • "pagination": {
    }
}

Get Webhook Event

Retrieve a webhook event by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

webhook_event_id
required
integer

The webhook event identifier.

Responses

Response samples

Content type
application/json
{
  • "webhook_event": {
    }
}

Webhook Subscriptions

Contains webhook metadata. Use these endpoints to add, remove, edit, or list webhook subscriptions.

List Webhook Subscriptions

Retrieve a list of webhook subscriptions.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

query Parameters
since_id
integer
limit
string

Maximum number of results to be returned

filters
Array of strings
Items Enum: "webhook_topic_id" "callback_url" "shared_secret" "created_at" "updated_at"

Filter subscription webhooks. Multiple filters can be passed in the array.

Responses

Response samples

Content type
application/json
{
  • "webhook_subscriptions": [
    ],
  • "pagination": {
    }
}

Create Webhook Subscription

Create a webhook subscription. For more information, refer to Register for Webhooks.

The subscription_payment_method_updated webhook is not supported by default for all Shopify shops installed prior to January 15th 2024 (2024-01-15). Please submit a support request for access.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Request Body schema: application/json
required
object
webhook_topic_id
required
integer [ 1 .. 10 ]
callback_url
required
string <uri>
shared_secret
required
string

Responses

Callbacks

Request samples

Content type
application/json
{
  • "webhook_subscription": {}
}

Response samples

Content type
application/json
{
  • "webhook_subscription": {
    }
}

Callback payload samples

Callback
Content type
application/json
{
  • "id": 1,
  • "external_id": "string",
  • "customer": "null",
  • "shop_id": 1,
  • "next_order_datetime": "2020-01-20T18:00:00Z",
  • "next_payment_datetime": "2020-01-20T18:00:00Z",
  • "next_processing_datetime": "2020-01-20T18:00:00Z",
  • "subscription_status": "active",
  • "status_changed_at": "2019-11-20T20:31:55Z",
  • "sca_url": "https://bank.com/pCkWhtgQQVM8W/sca",
  • "payment_method_token": "jik1w6HrCn17CxXPcKwHTGqqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG",
  • "payment_gateway_public_id": "jik1w6HrCn17CxXPcKwHTGqqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG",
  • "payment_rrule": "DTSTART:20200120T180000Z\\nRRULE:FREQ=MONTHLY\\nEXDATE:20200220T180000Z",
  • "payment_rrule_text": "Monthly",
  • "order_rrule": "DTSTART:20200120T180000Z\\nRRULE:FREQ=MONTHLY\\nEXDATE:20200220T180000Z",
  • "order_rrule_text": "Monthly",
  • "last_payment_datetime": "2019-11-20T20:55:26Z",
  • "last_order_datetime": "2019-11-20T20:55:26Z",
  • "last_processed_datetime": "2019-11-20T20:55:26Z",
  • "current_retries": 3,
  • "charged_currency": "CAD",
  • "base_to_charged_exchange_rate": 1,
  • "base_currency": "CAD",
  • "line_items": [
    ],
  • "shipping_lines": [
    ],
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "idempotency_key": "JwGdN55C4g1z5FXRO8Hp21CMxUxKyo6VcGSf3cUsjCgNyTtoeZcIsGM1We4p7pCe-0",
  • "placed_at": "2012-11-20T20:31:55Z",
  • "created_at": "2019-11-20T20:31:55Z",
  • "updated_at": "2019-11-20T20:31:55Z",
  • "percent_discount": 10,
  • "discount_code": "DISCOUNTCODE",
  • "customer_id": 1697912,
  • "billing_address_id": 11697812,
  • "shipping_address_id": 11697812,
  • "orders_processed": 1,
  • "last_failure_code": "card_expired",
  • "last_failure_details": {
    },
  • "last_failure_reason": "credit_card",
  • "note": "Staff note",
  • "order_note": "Customer note",
  • "order_count": 1
}

Get Webhook Subscription

Retrieve a webhook subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

webhook_subscription_id
required
integer

The webhook subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "webhook_subscription": {
    }
}

Update Webhook Subscription

Update a webhook subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

webhook_subscription_id
required
integer

The webhook subscription identifier.

Request Body schema: application/json
required
object (WebhookSubscriptionEntity)
id
integer
shop_id
integer
webhook_topic_id
integer
callback_url
string
shared_secret
string

Responses

Request samples

Content type
application/json
{
  • "webhook_subscription": {
    }
}

Response samples

Content type
application/json
{
  • "webhook_subscription": {
    }
}

Delete Webhook Subscription

Delete a webhook subscription by its id.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

webhook_subscription_id
required
integer

The webhook subscription identifier.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request",
  • "error_description": "The access token is missing"
}

Webhook Topics

Contains information about webhook topics. Use these endpoints to list all possible webhook topics.

List Webhook Topics

Retrieve a list of available webhook topics.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: 123456

The unique identifier of the shop.

Responses

Response samples

Content type
application/json
{
  • "webhook_topics": [
    ]
}