openapi: 3.0.0 info: title: Bold Subscriptions version: '1.0' description: |- 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. termsOfService: https://boldcommerce.com/terms-of-service contact: name: Contact Us url: https://developer-dashboard.boldcommerce.com/default/contactus servers: - url: https://api.boldcommerce.com security: - OAuthToken: [] - APIAccessToken: [] tags: - name: Subscriptions description: Contains information about subscriptions for your store and data associated with them. Use these endpoints to get, remove, edit, or list subscriptions. - name: Subscription Groups description: 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. - name: Subscription Line Items description: 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. - name: Subscription Orders description: 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. - name: Subscription Adjustments description: 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. - name: Future Orders description: Contains information about future orders for subscriptions. Use these endpoints to list future orders for a shop or individual subscriptions. - name: Convertible Adjustments description: Use these endpoints to create, update, or delete convertible adjustment plans, enabling automatic product conversions on subscription line items attached to a created plan. - name: Customers description: A child resource of Subscriptions. Contains information about customers for a subscription. Use these endpoints to manage customer data for a specific subscription. - name: Payment Methods description: 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. - name: Shops description: Contains information about your store, including store IDs, domains, platform, and admin configuration. Use these endpoints to manage store information and settings. - name: Webhook Events description: Contains information about webhook events, including webhook event ID, attempts, and webhook event metadata. Use these endpoints to get webhook event information. - name: Webhook Subscriptions description: Contains webhook metadata. Use these endpoints to add, remove, edit, or list webhook subscriptions. - name: Webhook Topics description: Contains information about webhook topics. Use these endpoints to list all possible webhook topics. externalDocs: description: For more information about Subscriptions, refer to the Overview. url: https://developer.boldcommerce.com/guides/subscriptions-v2 paths: /subscriptions/v1/shops/{shop_identifier}/customers: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' get: tags: - Customers summary: List Customers operationId: ListCustomers description: Retrieve a list of customers. responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Customers' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' parameters: - $ref: '#/components/parameters/customerSearch' - $ref: '#/components/parameters/customerStatus' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/page' /subscriptions/v1/shops/{shop_identifier}/customers/{customer_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' get: tags: - Customers summary: Get Customer operationId: GetCustomer description: Retrieve a customer by their id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' put: tags: - Customers summary: Update Customer operationId: UpdateCustomer description: Update a customer by their id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Customer' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/customers/{customer_id}/addresses: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' get: tags: - Customers summary: List Customer Addresses operationId: ListCustomerAddresses description: Retrieve a list of addresses for a customer. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' responses: '200': description: Successful operation content: application/json: schema: type: object properties: customer_addresses: type: array items: $ref: '#/components/schemas/CustomerAddressEntity' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' post: tags: - Customers summary: Create Customer Address operationId: CreateCustomerAddress description: Create an address for a customer. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' requestBody: required: true content: application/json: schema: type: object properties: customer_address: $ref: '#/components/schemas/UpdateCustomerAddressEntity' responses: '200': description: Successful operation content: application/json: schema: type: object properties: customer_address: $ref: '#/components/schemas/CustomerAddressEntity' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/customers/{customer_id}/addresses/{address_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' - $ref: '#/components/parameters/address_id_path_param' put: tags: - Customers summary: Update Customer Address operationId: UpdateCustomerAddress description: Update an address for a customer. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' - $ref: '#/components/parameters/address_id_path_param' requestBody: required: true content: application/json: schema: type: object properties: customer_address: $ref: '#/components/schemas/UpdateCustomerAddressEntity' responses: '200': description: Successful operation content: application/json: schema: type: object properties: customer_address: $ref: '#/components/schemas/CustomerAddressEntity' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' delete: tags: - Customers summary: Delete Customer Address operationId: DeleteCustomerAddress description: Delete an address from a customer. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' - $ref: '#/components/parameters/address_id_path_param' responses: '200': description: Successful operation '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/shop: get: tags: - Shops summary: Get Shop Info description: Retrieve basic information about a shop. operationId: GetShopInfo responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Shop' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' parameters: - $ref: '#/components/parameters/shop_identifier_path_param' /subscriptions/v1/shops/{shop_identifier}/subscriptions: get: tags: - Subscriptions summary: List Subscriptions operationId: ListSubscriptions description: Retrieve a list of subscriptions. responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/ListSubscriptions' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - schema: enum: - active - inactive - processing - scheduled - paused example: active in: query name: subscription_status description: Status of the subscriptions returned. Multiple statuses can be passed as an array. - schema: example: '1' in: query name: bold_platform_customer_id description: Customer Id of the subscriptions returned. Multiple customer ids can be passed as an array. - schema: type: string example: customer enum: - customer in: query name: expand description: Fields to expand on the subscription. Multiple fields can be passed as an array - schema: type: integer example: 5 in: query name: limit description: Maximum number of results to be returned - schema: type: string example: '?filter=lt(next_order_datetime:2021-11-15T00:00:00Z)+gt(next_order_datetime:2021-10-31T00:00:00Z)' in: query name: filter description: 'Accepts filtering options as described on the [Query & Pagination page](/guides/subscriptions-v2/resources/query-pagination). For example, to filter the next order date by a date interval, you could use the following parameter: ' - schema: type: string example: '?cursor= P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj' in: query name: cursor description: Returns the next page of results if supplied the `next` value from the previous pagination results. post: tags: - Subscriptions summary: Create Subscription operationId: CreateSubscription description: For more information about this endpoint, refer to [Create Subscriptions](/guides/subscriptions-v2/create-subscription). parameters: - $ref: '#/components/parameters/shop_identifier_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionEntity' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionError422' /subscriptions/v1/shops/{shop_identifier}/customers/{customer_id}/subscriptions: get: tags: - Customers summary: List Customer Subscriptions operationId: ListCustomerSubscriptions description: Retrieve a list of subscriptions for a single customer. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/customer_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscriptions' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/discount_code: put: tags: - Subscriptions summary: Update Discount Code operationId: UpdateDiscountCode description: Update the discount code applied to a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: type: object properties: discount_code: type: string example: HOLIDAY10 required: - discount_code responses: '200': description: Successful operation '400': description: Bad Request content: application/json: schema: oneOf: - type: object properties: errors: type: array items: type: string example: errors: - subscription not found - type: object properties: errors: type: array items: type: string example: errors: - 'Discount code "HOLIDAY10" rejected with reason: EXPIRED' delete: tags: - Subscriptions summary: Remove Discount Code operationId: RemoveDiscountCode description: Remove the discount code from a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: string example: errors: - subscription not found /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}: get: tags: - Subscriptions summary: Get Subscription operationId: GetSubscription description: Retrieve a subscription by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' put: tags: - Subscriptions summary: Update Subscription operationId: UpdateSubscription description: Update a subscription by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Subscription' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' patch: tags: - Subscriptions summary: Partial Update Subscription operationId: PartialUpdateSubscription description: Partially update a subscription by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PartialUpdateSubscription' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/intervals: get: tags: - Subscriptions summary: List Subscription Intervals operationId: ListSubscriptionIntervals description: Retrieve a list of available intervals for a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Intervals' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/interval/{subscription_interval_id}: put: tags: - Subscriptions summary: Update Subscription Interval operationId: UpdateSubscriptionInterval description: Update the interval of a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_interval_id_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/products_swap: put: tags: - Subscription Line Items summary: Swap Line Items operationId: SwapLineItems description: Swap line item products on a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SwapProduct' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/adjustments: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' post: summary: Create Subscription Adjustments operationId: CreateSubscriptionAdjustments tags: - Subscription Adjustments description: |- Creates adjustments for a subscription or its orders. For more information on subscription adjustments, refer to the [Adjust Subscription Orders](/guides/subscriptions-v2/adjust-subscription-orders) guide. responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionAdjustments' '400': description: Bad request content: application/json: schema: type: object properties: errors: type: object properties: message: type: string description: The detailed error message. enum: - only one of fields count, function, and relative count can be provided - invalid adjustment.action.type example: errors: message: only one of fields count, function, and relative count can be provided '422': description: Unprocessable entity content: application/json: schema: type: object properties: message: type: string description: The error summary. example: The given data was invalid. errors: type: object additionalProperties: type: array minItems: 1 items: type: string description: The detailed error message. example: The adjustments.0.target field is required. example: message: The given data was invalid. errors: adjustments.0.target: - The adjustments.0.target field is required. requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionAdjustments' examples: 'Trigger: One-time order adjustment by order count': value: adjustments: - name: Foundation Brush Cross-Sell description: Loving our beauty box? Up your game with the versatile, made-in-house Foundation Brush! target: order trigger: type: order_count count: 3 action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 1500 'Trigger: One-time order adjustment by relative order count': value: adjustments: - name: Dessert Upsell description: There's always room for dessert! Indulge in this dessert add-on with your next order. target: order trigger: type: order_count relative_count: 1 action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 700 'Trigger: Recurring order adjustment by function on order count': value: adjustments: - name: Loyalty Gift description: Enjoy a complementary gift every 5th order for being a loyal customer! target: order trigger: type: order_count function: step_size: 5 offset: 0 action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 0 'Trigger: One-time order adjustment by order datetime': value: adjustments: - name: 10th Anniversary Give-Away! description: Celebrate 10 years of cleaning the oceans! Spread our message in style with this free t-shirt! target: order trigger: type: order_datetime datetime: '2024-02-15T06:00:00Z' action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 0 'Trigger: Subscription adjustment by order count': value: adjustments: - name: Samples Up! (Trial End) description: Coffee samples hit the spot!? Time to start receiving the real deal! target: subscription trigger: type: order_count count: 2 action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 1500 'Trigger: Subscription adjustment by relative order count': value: adjustments: - name: Gryffindor Upsell description: Are you Slytherin? Are you Gryffindor? Start receiving a second box on your next order and find out! target: subscription trigger: type: order_count relative_count: 1 action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 700 'Trigger: Subscription adjustment by order datetime': value: adjustments: - name: More Family. More Fun! description: Expecting? Add a newborn to your baby supply plan in advance! target: subscription trigger: type: order_datetime datetime: '2024-01-20T06:00:00Z' action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 3500 'Action: Add Product': description: |- Adds a product to a subscription or its orders. **Supported targets** * `subscription` * `order` value: adjustments: - name: Foundation Brush Cross-Sell description: Loving our beauty box? Up your game with the versatile, made-in-house Foundation Brush! target: order trigger: type: order_count count: 3 action: type: add_line_item platform_variant_id: '17169270472755' platform_product_id: '1841889509427' quantity: 1 price: 1500 'Action: Update Line Item Quantity': description: |- Updates the quantity of line item to a subscription or its orders. **Supported targets** * `subscription` * `order` value: adjustments: - name: Coffee Bean Upsell description: Coffee is temporary but mornings are forever. Prepare for the future and add another bag of coffee to your order! target: order trigger: type: order_count count: 3 action: type: update_line_item_quantity subscription_line_item_id: 35236 quantity: 3 get: parameters: - $ref: '#/components/parameters/filter_subscription_adjustments_query_param' summary: List Subscription Adjustments operationId: ListSubscriptionAdjustments tags: - Subscription Adjustments description: Lists adjustments for a subscription or its orders. responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionAdjustments' delete: parameters: - $ref: '#/components/parameters/filter_subscription_adjustments_query_param' summary: Delete Subscription Adjustments operationId: DeleteSubscriptionAdjustments tags: - Subscription Adjustments description: Deletes adjustments for a subscription or its orders. responses: '200': description: Successful operation content: application/json: schema: type: array minItems: 0 maxItems: 0 items: {} /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/adjustments/{adjustment_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/subscription_adjustment_id_path_param' get: summary: Get Subscription Adjustment by ID operationId: GetSubscriptionAdjustmentByID tags: - Subscription Adjustments description: Gets an adjustment by its ID. responses: '200': description: Successful operation content: application/json: schema: type: object properties: adjustment: $ref: '#/components/schemas/SubscriptionAdjustment' delete: summary: Delete Subscription Adjustment by ID operationId: DeleteSubscriptionAdjustmentByID tags: - Subscription Adjustments description: Deletes an adjustment by its ID. responses: '200': description: Successful operation content: application/json: schema: type: array minItems: 0 maxItems: 0 items: {} '404': description: Not found content: application/json: schema: type: object properties: errors: type: object properties: message: type: string enum: - not found () example: errors: message: not found (subscriptions:1234dde7622ab0.56787371) /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/orders: get: tags: - Subscription Orders summary: List Orders operationId: ListOrders description: Retrieve a list of subscription orders for a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - schema: type: integer in: query name: page description: The desired page number for the paginated result - schema: type: integer in: query description: Maximum number of results to be returned name: limit responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionOrders' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/orders/{order_id}: get: tags: - Subscription Orders summary: Get Order operationId: GetOrder description: Retrieve a subscription order for a subscription by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/order_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionOrder' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/future_orders: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' get: summary: List Future Orders operationId: ListFutureOrders tags: - Future Orders description: |- Lists future subscription orders for the shop. For more information, refer to the [View Future Orders](/guides/subscriptions-v2/view-future-orders#querying-all-active-subscription-orders) guide. parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/filter_future_orders_query_param' - $ref: '#/components/parameters/filter_future_order_subscriptions_query_param' - $ref: '#/components/parameters/cursor' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/FutureOrders' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/future_orders: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' get: summary: List Future Orders by Subscription ID operationId: ListFutureOrdersBySubscriptionID tags: - Future Orders description: |- Lists future orders for a subscription. For more information, refer to the [View Future Orders](/guides/subscriptions-v2/view-future-orders#querying-orders-by-subscription-id) guide. parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/filter_future_orders_query_param' - $ref: '#/components/parameters/cursor' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/FutureOrders' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/convertible_adjustment_groups: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' post: tags: - Convertible Adjustments summary: Create Convertible Adjustment Group description: |- 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](/api/subscriptions#tag/Convertible-Adjustments/operation/CreateConvertibleAdjustmentGroupItems) to attach the created convertible adjustment group items to the adjustment group. operationId: CreateConvertibleAdjustmentGroup requestBody: required: true content: application/json: schema: type: object required: - data properties: data: type: object required: - convertible_adjustment_group properties: convertible_adjustment_group: $ref: '#/components/schemas/ConvertibleAdjustmentGroup' responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object required: - convertible_adjustment_group properties: convertible_adjustment_group: $ref: '#/components/schemas/ConvertibleAdjustmentGroup' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: The error summary. example: The selected data.convertible adjustment group.on cycle end is invalid. errors: type: object additionalProperties: type: array minItems: 1 items: type: string description: The detailed error message. example: The selected data.convertible adjustment group.on cycle end is invalid. example: message: The selected data.convertible adjustment group.on cycle end is invalid. errors: data.convertible_adjustment.on_cycle_end: - The selected data.convertible adjustment group.on cycle end is invalid. /subscriptions/v1/shops/{shop_identifier}/convertible_adjustment_groups/{adjustment_id}/items: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/convertible_adjustment_group_id_path_param' post: tags: - Convertible Adjustments summary: Create Convertible Adjustment Group Items description: 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. operationId: CreateConvertibleAdjustmentGroupItems requestBody: required: true content: application/json: schema: type: object required: - data properties: data: type: object required: - items properties: items: type: array minItems: 2 uniqueItems: true items: $ref: '#/components/schemas/ConvertibleAdjustmentGroupItemEntity' example: data: items: - type: initial_product discount_type: no_discount - type: product product: platform_product_id: '7873884094619' platform_variant_id: '44147851264155' discount_type: percentage discount_value: 50 - type: product product: platform_product_id: '7873885831323' platform_variant_id: '44147858473115' discount_type: percentage discount_value: 50 responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object properties: items: type: array minItems: 2 uniqueItems: true items: $ref: '#/components/schemas/ConvertibleAdjustmentGroupItem' example: data: items: - id: 81 shop_platform_app_id: 1007 convertible_adjustment_group_id: 20 type: initial_product discount_type: no_discount discount_value: 0 product: null - id: 82 shop_platform_app_id: 1007 convertible_adjustment_group_id: 20 type: product discount_type: percentage discount_value: 50 product: id: 82 convertible_adjustment_group_id_item_id: 82 platform_product_id: '7873884094619' platform_variant_id: '44147851264155' created_at: '2024-03-19T20:42:47Z' updated_at: '2024-03-19T20:42:47Z' deleted_at: null - id: 83 shop_platform_app_id: 1007 convertible_adjustment_group_id: 20 type: product discount_type: percentage discount_value: 50 product: id: 83 convertible_adjustment_group_id_item_id: 83 platform_product_id: '7873885831323' platform_variant_id: '44147858473115' created_at: '2024-03-19T20:42:47Z' updated_at: '2024-03-19T20:42:47Z' deleted_at: null '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: message: type: string description: The error message. example: 'validating items of type "product" failed with reason: platform "[product]:[variant]" data was not found for some items: 123:456' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '404': description: Not found content: application/json: schema: type: object properties: errors: type: object properties: message: type: string enum: - not found () '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: The error summary. example: The selected data.items.0.type is invalid. errors: type: object additionalProperties: type: array minItems: 1 items: type: string description: The detailed error message. example: The selected data.items.0.type is invalid. example: errors: data.items.0.type: - The selected data.items.0.type is invalid. '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: object properties: message: type: string description: The error message. example: 'validating items of type "product" failed with reason: failed to fetch variants: variant data missing from response (subscriptions:123.456)' delete: tags: - Convertible Adjustments summary: Delete Convertible Adjustment Group Items description: Deletes all convertible adjustment group items from a convertible adjustment group. operationId: DeleteConvertibleAdjustmentGroupItems responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object properties: deleted_item_count: type: integer description: The number of deleted convertible adjustment group items from the convertible adjustment group. example: 1 '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '404': description: Not found content: application/json: schema: type: object properties: errors: type: object properties: message: type: string enum: - not found () /subscriptions/v1/shops/{shop_identifier}/convertible_adjustment_groups/{adjustment_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/convertible_adjustment_group_id_path_param' delete: tags: - Convertible Adjustments summary: Delete Convertible Adjustment Group description: Deletes a convertible adjustment group and its items for a store. operationId: DeleteConvertibleAdjustmentGroup responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object properties: convertible_adjustment_group_id: type: integer example: 2 '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '404': description: Not found content: application/json: schema: type: object properties: errors: type: object properties: message: type: string enum: - not found () put: tags: - Convertible Adjustments summary: Update Convertible Adjustment Group description: Updates a convertible adjustment group for a store. operationId: UpdateConvertibleAdjustmentGroup requestBody: required: true content: application/json: schema: type: object required: - data properties: data: type: object required: - convertible_adjustment_group properties: convertible_adjustment_group: $ref: '#/components/schemas/ConvertibleAdjustmentGroup' responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object required: - convertible_adjustment_group properties: convertible_adjustment_group: $ref: '#/components/schemas/ConvertibleAdjustmentGroup' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: The error summary. example: The selected data.convertible adjustment group.on cycle end is invalid. errors: type: object additionalProperties: type: array minItems: 1 items: type: string description: The detailed error message. example: The selected data.convertible adjustment group.on cycle end is invalid. example: message: The selected data.convertible adjustment group.on cycle end is invalid. errors: data.convertible_adjustment.on_cycle_end: - The selected data.convertible adjustment group.on cycle end is invalid. /subscriptions/v1/shops/{shop_identifier}/convertible_adjustment_groups/{adjustment_id}/items/{adjustment_item_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/convertible_adjustment_group_id_path_param' - $ref: '#/components/parameters/convertible_adjustment_group_item_id_path_param' delete: tags: - Convertible Adjustments summary: Delete Convertible Adjustment Group Item description: Deletes a convertible adjustment group item from a convertible adjustment group using the convertible adjustment group item ID operationId: DeleteConvertibleAdjustmentGroupItem responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object properties: item_id: type: integer description: The convertible adjustment group item identifier deleted from the convertible adjustment plan. example: 2 '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '404': description: Not found content: application/json: schema: type: object properties: errors: type: object properties: message: type: string enum: - not found () put: tags: - Convertible Adjustments summary: Update Convertible Adjustment Group Item description: Updates a convertible adjustment group item from a convertible adjustment group using the convertible adjustment group item ID operationId: UpdateConvertibleAdjustmentGroupItem requestBody: required: true content: application/json: schema: type: object required: - data properties: data: type: object required: - item properties: item: $ref: '#/components/schemas/ConvertibleAdjustmentGroupItemEntity' example: data: item: type: product product: platform_product_id: '7873884094619' platform_variant_id: '44147851264155' discount_type: percentage discount_value: 50 responses: '200': description: Successful operation content: application/json: schema: type: object properties: data: type: object properties: item: $ref: '#/components/schemas/ConvertibleAdjustmentGroupItem' example: data: item: id: 82 shop_platform_app_id: 1007 convertible_adjustment_group_id: 20 type: product discount_type: percentage discount_value: 50 product: id: 82 convertible_adjustment_group_id_item_id: 82 platform_product_id: '7873884094619' platform_variant_id: '44147851264155' created_at: '2024-03-19T20:42:47Z' updated_at: '2024-03-19T20:42:47Z' deleted_at: null '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: message: type: string description: The error message. example: 'validating items of type "product" failed with reason: platform "[product]:[variant]" data was not found for some items: 123:456' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '404': description: Not found content: application/json: schema: type: object properties: errors: type: object properties: message: type: string enum: - not found () '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: The error summary. example: The selected data.item.type is invalid. errors: type: object additionalProperties: type: array minItems: 1 items: type: string description: The detailed error message. example: The selected data.item.type is invalid. example: errors: data.item.type: - The selected data.type is invalid. '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: object properties: message: type: string description: The error message. example: 'validating items of type "product" failed with reason: failed to fetch variants: variant data missing from response (subscriptions:123.456)' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/payment_method: get: tags: - Payment Methods summary: Get Payment Method operationId: GetPaymentMethod description: Retrieve the current payment method information of a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PaymentMethod' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/payment_method_email: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' post: tags: - Payment Methods summary: Trigger Update Payment Method Email operationId: TriggerUpdatePaymentMethodEmail description: |- **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. responses: '200': description: OK content: application/json: schema: type: object properties: {} /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/payment_methods: get: tags: - Payment Methods summary: List Payment Methods operationId: ListPaymentMethods description: Retrieve a list of available payment methods for a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/PaymentMethods' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/line_items: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' patch: tags: - Subscription Line Items summary: Update Line Items operationId: UpdateLineItems description: |- Update the line items of a subscription. Refer to [Manage Subscription Line Items](/guides/subscriptions-v2/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.* parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionLineItems' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionUpdateLineItems' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' post: tags: - Subscriptions summary: Create Line Items description: |- Add one or more line items to a subscription. Refer to [Create Subscription Line Items](/guides/subscriptions-v2/create-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. operationId: CreateLineItems requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionLineItems' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/CreateLineItemsResponse' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' '403': description: Adding line items to multi-currency subscriptions is not supported at this time. '404': description: Subscription, product variant, or subscription group not found. /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/next_order_datetime: put: tags: - Subscription Orders summary: Update Next Order Datetime operationId: UpdateNextOrderDatetime description: Update the datetime of the next subscription order in [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionNextOrderDate' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/recover: put: tags: - Subscription Orders summary: Unskip Previously Skipped Order operationId: UnskipPreviouslySkippedOrder description: Restore a previously skipped future subscription order. Specify the date of the order to be unskipped. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnskipSubscriptionOrder' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/skip: put: tags: - Subscription Orders summary: Skip Subscription Order operationId: SkipSubscriptionOrder description: Skip a subscription's upcoming order by date. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SkipSubscriptionOrder' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/activate: post: tags: - Subscriptions summary: Reactivate Subscription operationId: ReactivateSubscription description: Reactivate an inactive or cancelled subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/cancel: post: tags: - Subscriptions summary: Cancel Subscription operationId: CancelSubscription description: Cancel a subscription and any future orders. Cancelled subscriptions will appear as 'inactive'. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/pause: post: tags: - Subscriptions summary: Pause Subscription operationId: PauseSubscription description: Pause a subscription and any future orders. Paused orders will still appear as 'active'. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/line_items/{line_item_id}: delete: tags: - Subscription Line Items summary: Delete Line Item operationId: DeleteLineItem description: Delete a line item from a subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/line_item_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Subscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' get: tags: - Subscription Line Items summary: Get Line Item operationId: GetLineItem description: Retrieve the details of a specific line item from a given subscription. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/line_item_id_path_param' responses: '200': description: Successful operation content: application/json: schema: type: object properties: subscription_line_item: $ref: '#/components/schemas/LineItemEntity' examples: success-example: value: subscription_line_item: id: 1 subscription_id: 1 platform_id: ABC123 platform_product_id: '1357908642' platform_variant_id: '2468097531' subscription_group_id: 1 subscription_group_billing_rules_id: 1 title: Monthly Expansion Pack product_name: Monthly Expansion Pack variant_name: Default Title sku: SKU-113-Red url: https://example-store.example.com/monthly-expansion-pack image: '' quantity: 1 price: 3500 price_charged: 3200 discounted_price: 3200 discounted_price_charged: 3200 full_price: 3200 full_price_charged: 3200 requires_shipping: false grams: 2200 weight: 2.2 weight_unit: kg taxable: true discounts: - id: 1 subscription_line_item_id: 1 shop_id: 5 full_price: 5 discount_type: percentage percentage_value: 10 fixed_value: 0 fixed_value_charged: 0 description: Subscription discount (10%) for Monthly Expansion Pack created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' deleted_at: '2019-11-20T20:31:55Z' prepaid_metadata: id: 1 line_item_id: 2 prepaid_duration: 2 current_recurrence_count: 2 prepaid_continue: no_continue line_item_attributes: - name: size_preference value: XL created_at: '2021-01-17T20:30:40Z' updated_at: '2021-01-17T20:30:40Z' subscription_id: 1 line_item_id: 1 created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' '404': description: Subscription or line item not found /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/line_items/{line_item_id}/products_swap: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/line_item_id_path_param' get: tags: - Subscription Line Items summary: List Swappable Products by Line Item operationId: ListSwappableProductsByLineItem responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SwappableProducts' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Retrieve a list of swappable products for a subscription line item. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/line_item_id_path_param' - schema: type: integer in: query name: limit description: Maximum number of results to be returned - schema: type: integer in: query name: page description: The desired page number for the paginated result /subscriptions/v1/shops/{shop_identifier}/selection_options: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' get: tags: - Subscription Groups summary: List Selection Options description: 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. operationId: ListSelectionOptions parameters: - schema: type: string in: query name: cursor description: A base 64 encoded cursor. example: '?cursor=P2lkPTU1' - schema: type: string in: query name: filter description: Accepts filtering options as described on the [Query & Pagination page](/guides/subscriptions-v2/resources/query-pagination). example: '?filter=in(platform_entity_id:1,2,3)' - schema: type: string in: query name: expand description: Fields to expand on the selection options. Currently accepts `subscription_group` and `products` example: '?expand=subscription_group&expand=products' - schema: type: integer in: query name: limit description: Limit the number of returned items. example: '?limit=3L9' - $ref: '#/components/parameters/latest' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SelectionOptions' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscription_groups: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' get: tags: - Subscription Groups summary: List Subscription Groups operationId: ListSubscriptionGroups description: Retrieve a list of subscription groups. responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionGroups' examples: example-1: value: subscription_groups: - id: 3 shop_id: 1 internal_name: Standard Subscription is_enabled: true platform_id: gid://shopify/SellingPlanGroup/132016692 allow_prepaid: false is_prepaid_only: false should_continue_prepaid: false continue_prepaid_type: as_prepaid percent_discount: 11 minimum_order_count_before_cancellable: 0 is_product_swappable: false is_subscription_only: false selection_type: products group_type: selectable selectable_daily_allowed: false selectable_weekly_allowed: false selectable_yearly_allowed: false selectable_max_interval_frequency: 0 fixed_interval_type: monthly is_fixed_billing: false can_add_to_cart: true allow_buffer_days: true discount_type: fixed fixed_discount: 10 created_at: '2019-11-20T20:50:07Z' updated_at: '2019-11-20T20:50:07Z' deleted_at: null active_subscribers_count: 1 billing_rules: - id: 1 shop_id: 1 subscription_group_id: 1 interval_number: 1 interval_type: month interval_name: Monthly week_type: '' week_day: 0 month_type: purchase_day month_day: '' month_occurrence: '' month_occurrence_day: '' year_type: '' year_month: '' year_occurrence: '' year_occurrence_day: '' billing_rule: FREQ=MONTHLY created_at: '2019-11-20T20:50:07Z' updated_at: '2019-11-20T20:50:07Z' deleted_at: null selection_options: - id: 1 shop_id: 1 subscription_group_id: 1 platform_entity_id: '1357908642' created_at: '2019-11-20T20:50:07Z' updated_at: '2019-11-20T20:50:07Z' deleted_at: null entity_id: 1472540 prepaid_durations: - {} '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' post: tags: - Subscription Groups summary: Create Subscription Group operationId: CreateSubscriptionGroup description: Create a subscription group. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionGroup' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionGroup' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscription_groups/{group_id}: get: tags: - Subscription Groups summary: Get Subscription Group operationId: GetSubscriptionGroup description: Retrieve a subscription group by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/group_id_path_param' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionGroup' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' put: tags: - Subscription Groups summary: Update Subscription Group operationId: UpdateSubscriptionGroup description: Update a subscription group by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/group_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionGroup' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/SubscriptionGroup' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' delete: tags: - Subscription Groups summary: Delete Subscription Group operationId: DeleteSubscriptionGroup description: Delete a subscription group by its id. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/group_id_path_param' responses: '200': description: Successful operation '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/webhooks/topics: get: summary: List Webhook Topics operationId: ListWebhookTopics tags: - Webhook Topics responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/WebhookTopics' examples: example: value: webhook_topics: - id: 1 topic_name: subscription_created - id: 2 topic_name: subscription_updated - id: 3 topic_name: subscription_order_created - id: 4 topic_name: customer_created - id: 5 topic_name: customer_updated - id: 6 topic_name: subscription_order_transaction_failed - id: 7 topic_name: subscription_order_max_retries_reached - id: 8 topic_name: subscription_payment_method_updated - id: 9 topic_name: subscription_upcoming_order - id: 10 topic_name: subscription_expiring_payment - id: 12 topic_name: subscription_cancelled - id: 13 topic_name: subscription_paused - id: 14 topic_name: subscription_resumed - id: 15 topic_name: subscription_reactivated - id: 16 topic_name: subscription_frequency_updated - id: 17 topic_name: subscription_quantity_updated - id: 18 topic_name: subscription_credit_card_updated - id: 19 topic_name: subscription_shipping_address_updated - id: 20 topic_name: subscription_payment_failed - id: 21 topic_name: subscription_skipped - id: 22 topic_name: subscription_line_items_added '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Retrieve a list of available webhook topics. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' /subscriptions/v1/shops/{shop_identifier}/webhooks/subscriptions: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' get: summary: List Webhook Subscriptions operationId: ListWebhookSubscriptions tags: - Webhook Subscriptions responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptions' examples: example: value: webhook_subscriptions: - id: 1 shop_id: 1 webhook_topic_id: 1 callback_url: yourapp.com/v2/sub-created created_at: '2020-09-17T18:27:03Z' updated_at: '2020-09-17T18:27:03Z' deleted_at: null - id: 1 shop_id: 1 webhook_topic_id: 2 callback_url: yourapp.com/sub-updated created_at: '2020-08-17T18:27:03Z' updated_at: '2020-08-17T18:27:03Z' deleted_at: null pagination: limit: 10 count: 2 total: 2 total_pages: 1 '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Retrieve a list of webhook subscriptions. parameters: - schema: type: integer in: query name: since_id description: '' - schema: type: string in: query name: limit description: Maximum number of results to be returned - schema: type: array items: type: string enum: - webhook_topic_id - callback_url - shared_secret - created_at - updated_at in: query name: filters description: Filter subscription webhooks. Multiple filters can be passed in the array. post: summary: Create Webhook Subscription operationId: CreateWebhookSubscription tags: - Webhook Subscriptions responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: |- Create a webhook subscription. For more information, refer to [Register for Webhooks](/guides/subscriptions-v2/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](https://support.boldcommerce.com/hc/en-us/requests/new?ticket_form_id=132106) for access. requestBody: content: application/json: schema: type: object properties: webhook_subscription: type: object required: - webhook_topic_id - callback_url - shared_secret properties: webhook_topic_id: type: integer example: 10 minimum: 1 maximum: 10 callback_url: type: string format: uri example: https://webhooks.shop.com shared_secret: type: string example: exMh194qw8JD@A50dA^P required: - webhook_subscription callbacks: Subscription created: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_created post: summary: Subscription Created requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_updated post: summary: Subscription Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription order created: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_order_created post: summary: Subscription Order Created requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionOrder' responses: '200': description: Successful operation Customer created: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - customer_created post: summary: Customer Created requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerEntity' responses: '200': description: Successful operation Customer updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - customer_updated post: summary: Customer Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Customer' responses: '200': description: Successful operation Subscription order transaction failed: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_order_transaction_failed post: summary: Subscription Order Transaction Failed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionOrderTransactionFailed' responses: '200': description: Successful operation Subscription order max retries reached: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_order_max_retries_reached post: summary: Subscription Order Max Retries Reached requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionOrderTransactionFailed' responses: '200': description: Successful operation Subscription payment method updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_payment_method_updated post: summary: Subscription Payment Method Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Upcoming order: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_upcoming_order post: summary: Upcoming Order requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Subscription' responses: '200': description: Successful operation Expiring payment method: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_expiring_payment post: summary: Expiring Payment Method requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAndPaymentMethod' responses: '200': description: Successful operation Subscription cancelled: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_cancelled post: summary: Subscription Cancelled requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription frequency updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_frequency_updated post: summary: Subscription Frequency Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription credit card updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_credit_card_updated post: summary: Subscription Credit Card Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription payment failed: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_payment_failed post: summary: Subscription Payment Failed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription paused: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_paused post: summary: Subscription Paused requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription resumed: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_resumed post: summary: Subscription Resumed requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription reactivated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_reactivated post: summary: Subscription Reactivated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription shipping address updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_shipping_address_updated post: summary: Subscription Shipping Address Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription quantity updated: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_quantity_updated post: summary: Subscription Quantity Updated requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription skipped: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_skipped post: summary: Subscription Skipped requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation Subscription line items added: '{$request.body#/webhook_subscription.callback_url}': parameters: - $ref: '#/components/parameters/event_actor_type_header' - $ref: '#/components/parameters/shop_identifier_header' - in: header name: Event-Identifier required: true description: The webhook topic name of the event. schema: type: string enum: - subscription_line_items_added post: summary: Subscription Line Items Added requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntity' responses: '200': description: Successful operation /subscriptions/v1/shops/{shop_identifier}/webhooks/subscriptions/{webhook_subscription_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/webhook_subscription_id_path_param' get: summary: Get Webhook Subscription operationId: GetWebhookSubscription tags: - Webhook Subscriptions responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Retrieve a webhook subscription by its id. put: summary: Update Webhook Subscription operationId: UpdateWebhookSubscription tags: - Webhook Subscriptions requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WebhookSubscription' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Update a webhook subscription by its id. delete: tags: - Webhook Subscriptions summary: Delete Webhook Subscription operationId: DeleteWebhookSubscription responses: '200': description: Successful operation '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Delete a webhook subscription by its id. /subscriptions/v1/shops/{shop_identifier}/webhooks/events: get: summary: List Webhook Events operationId: ListWebhookEvents tags: - Webhook Events responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WebhookEvents' examples: example: value: webhook_events: - id: 0 shop_id: 0 webhook_subscription_id: 0 webhook_topic_id: 0 uuid: string attempts: 0 last_response_status_code: string delivered_at: string created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' deleted_at: null pagination: limit: 10 count: 1 total: 1 total_pages: 1 '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Retrieve a list of webhook events. parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - schema: type: integer in: query name: since_id - schema: type: string in: query name: limit description: Maximum number of results to be returned - schema: type: array items: type: string enum: - shop_id - webhook_subscription_id - webhook_topic_id - uuid - attempts - last_response_status_code - id - created_at - updated_at - delivered_at in: query name: filters description: Filter event webhooks. Mulitple filters can be passed in the array. /subscriptions/v1/shops/{shop_identifier}/webhooks/events/{webhook_event_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/webhook_event_id_path_param' get: summary: Get Webhook Event operationId: GetWebhookEvent description: Retrieve a webhook event by its id. tags: - Webhook Events responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/alternative_payments: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' get: summary: List Alternative Payment Methods operationId: ListAlternativePaymentMethods tags: - Payment Methods responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AlternatePaymentMethod' description: Retrieve a list of alternative payment methods for a subscription. post: summary: Create Alternative Payment Method operationId: CreateAlternativePaymentMethods tags: - Payment Methods responses: '200': description: OK content: application/json: schema: description: '' type: object properties: alternative_payment_methods: type: array uniqueItems: true minItems: 1 items: required: - subscription_id - public_payment_token properties: subscription_id: type: number public_payment_token: type: string minLength: 1 required: - alternative_payment_methods examples: example-1: value: alternative_payment_methods: - subscription_id: 0 public_payment_token: string requestBody: content: application/json: schema: description: '' type: object properties: alternative_payment_methods: type: array uniqueItems: true minItems: 1 maxItems: 1 items: type: object properties: type: type: string minLength: 1 payment_details: type: object properties: card_number: type: string minLength: 1 security_key: type: string required: - card_number - security_key required: - type required: - alternative_payment_methods examples: example-1: value: alternative_payment_methods: - type: gift_card payment_details: card_number: ABC1234 security_key: '123' example-2: value: alternative_payment_methods: - type: string payment_details: card_number: string security_key: '0' description: '' description: Add an alternate payment method to a subscription. /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/alternative_payments/{payment_public_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - schema: type: string name: payment_public_id in: path required: true delete: summary: Delete Alternative Payment Method operationId: DeleteAlternativePaymentMethod tags: - Payment Methods responses: '200': description: OK description: Remove an alternative payment method from a subscription its paymentPublicID. /subscriptions/v1/shops/{shop_identifier}/subscription_groups/{group_id}/selection_options/{selection_option_id}: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/group_id_path_param' - schema: type: string name: selection_option_id in: path required: true description: Selection option ID of the item to be deleted from the group. delete: summary: Delete Selection Option by ID operationId: DeleteSelectionOptionByID responses: '200': description: Successful operation '401': description: Unauthorized '404': description: Subscription group or selection option not found description: Delete a selection option from inside a subscription group. tags: - Subscription Groups /subscriptions/v1/shops/{shop_identifier}/subscription_groups/{group_id}/selection_options: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/group_id_path_param' delete: summary: Delete Selection Option by Filter operationId: DeleteSelectionOptionByFilter responses: '200': description: Successful operation '401': description: Unauthorized '404': description: Subscription group or selection option not found description: Delete one or more selection options from inside a subscription group. tags: - Subscription Groups parameters: - schema: type: string in: query name: filter description: '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)' required: true post: tags: - Subscription Groups summary: Add Selection Options by Platform Product ID(s) operationId: AddSelectionOptionsByPlatformIDs description: | Add one or more selection options from inside a subscription group. requestBody: content: application/json: schema: description: '' type: object x-examples: example-1: subscription_group: selection_options: platform_entity_ids: [] properties: subscription_group: type: object required: - selection_options properties: selection_options: type: object required: - platform_entity_ids properties: platform_entity_ids: type: array description: These are product ids we are look items: type: integer required: - subscription_group examples: Example Body: value: subscription_group: selection_options: platform_entity_ids: - 7021943390389 - 7003068956853 - 7014441746613 description: 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. responses: '200': description: Successful operation '401': description: Unauthorized '404': description: Subscription group or selection option not found /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/line_items/{line_item_id}/attributes: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/line_item_id_path_param' post: description: Add a new set of attributes to a line item. tags: - Subscription Line Items summary: Create Line Item Attributes operationId: CreateLineItemAttributes responses: '200': description: Successful operation content: application/json: schema: type: object properties: line_item_attributes: type: array items: $ref: '#/components/schemas/LineItemAttributeEntity' examples: success-example: value: line_item_attributes: - name: size_preference value: XL created_at: '2021-01-17T20:30:40Z' updated_at: '2021-01-17T20:30:40Z' subscription_id: 1 line_item_id: 1 - name: color_preference value: green created_at: '2021-01-17T20:30:40Z' updated_at: '2021-01-17T20:30:40Z' subscription_id: 1 line_item_id: 1 '404': description: Subscription or line item not found requestBody: content: application/json: schema: type: object properties: line_item_attributes: type: array items: $ref: '#/components/schemas/LineItemAttributeEntity' examples: request-body-example: value: line_item_attributes: - name: size_preference value: XL - name: color_preference value: green patch: tags: - Subscription Line Items summary: Update Line Item Attributes operationId: UpdateLineItemAttributes description: |- 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. responses: '200': description: Successful operation content: application/json: schema: type: object properties: subscription_line_item: $ref: '#/components/schemas/LineItemEntity' examples: success-example: value: subscription_line_item: id: 1 subscription_id: 1 platform_id: ABC123 platform_product_id: '1357908642' platform_variant_id: '2468097531' subscription_group_id: 1 subscription_group_billing_rules_id: 1 title: Monthly Expansion Pack product_name: Monthly Expansion Pack variant_name: Default Title sku: SKU-113-Red url: https://example-store.example.com/monthly-expansion-pack image: '' quantity: 1 price: 3500 price_charged: 3200 discounted_price: 3200 discounted_price_charged: 3200 full_price: 3200 full_price_charged: 3200 requires_shipping: false grams: 2200 weight: 2.2 weight_unit: kg taxable: true discounts: - id: 1 subscription_line_item_id: 1 shop_id: 5 full_price: 5 discount_type: percentage percentage_value: 10 fixed_value: 0 fixed_value_charged: 0 description: Subscription discount (10%) for Monthly Expansion Pack created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' deleted_at: '2019-11-20T20:31:55Z' prepaid_metadata: id: 1 line_item_id: 2 prepaid_duration: 2 current_recurrence_count: 2 prepaid_continue: no_continue line_item_attributes: - name: size_preference value: XL created_at: '2021-01-17T20:30:40Z' updated_at: '2021-01-17T20:30:40Z' subscription_id: 1 line_item_id: 1 - name: color_preference value: green created_at: '2021-01-17T20:30:40Z' updated_at: '2021-01-17T20:30:40Z' subscription_id: 1 line_item_id: 1 created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' '404': description: Subscription or line item not found requestBody: content: application/json: schema: type: object properties: line_item_attributes: type: array items: $ref: '#/components/schemas/LineItemAttributeEntity' examples: request-body-example: value: line_item_attributes: - name: size_preference value: XL - name: color_preference value: green /subscriptions/v1/shops/{shop_identifier}/subscriptions/{subscription_id}/line_items/{line_item_id}/prepaid_metadata: parameters: - $ref: '#/components/parameters/shop_identifier_path_param' - $ref: '#/components/parameters/subscription_id_path_param' - $ref: '#/components/parameters/line_item_id_path_param' post: tags: - Subscription Line Items summary: Create Line Item Prepaid Metadata operationId: CreateLineItemPrepaidMetadata description: |- 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`. responses: '200': description: Successful operation content: application/json: schema: type: object properties: prepaid_metadata: $ref: '#/components/schemas/PrepaidMetadataEntity' examples: success-example: value: prepaid_metadata: id: 1 line_item_id: 2 prepaid_duration: 2 current_recurrence_count: 2 prepaid_continue: no_continue '404': description: Subscription or Line Item Not Found requestBody: content: application/json: schema: type: object properties: prepaid_metadata: $ref: '#/components/schemas/PrepaidMetadataEntity' examples: request-body-example: value: prepaid_metadata: prepaid_continue: as_prepaid prepaid_duration: 6 current_recurrence_count: 6 patch: summary: Update Line Item Prepaid Metadata operationId: UpdateLineItemPrepaidMetadata tags: - Subscription Line Items description: |- 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](/api/subscriptions#tag/Subscriptions#operation/CreateLineItemPrepaidMetadata) endpoint. responses: '200': description: Successful operation content: application/json: schema: type: object properties: prepaid_metadata: $ref: '#/components/schemas/PrepaidMetadataEntity' examples: success-example: value: prepaid_metadata: id: 1 line_item_id: 2 prepaid_duration: 2 current_recurrence_count: 2 prepaid_continue: no_continue '404': description: Subscription or Line Item Not Found requestBody: content: application/json: schema: type: object properties: prepaid_metadata: $ref: '#/components/schemas/PrepaidMetadataEntity' examples: request-body-example: value: prepaid_metadata: prepaid_continue: no_continue prepaid_duration: 6 current_recurrence_count: 6 components: securitySchemes: OAuthToken: type: oauth2 flows: authorizationCode: authorizationUrl: https://apps.boldapps.net/accounts/dashboard/authorize tokenUrl: https://api.boldcommerce.com/auth/oauth2/token scopes: {} description: Authenticates an API request from a [public integration](/guides/subscriptions-v2/resources/glossary#public-integration). Generate this token in the [Developer Dashboard](https://developer-dashboard.boldcommerce.com/default/dashboard). Refer to [Build Public Integrations](/guides/subscriptions-v2/public-integrations) for more information. APIAccessToken: type: apiKey name: API Access Token in: header description: Authenticates an API request from a [private integration](/guides/subscriptions-v2/resources/glossary#private-integration). Generate this token in the [Bold Account Center](https://account.boldcommerce.com/). Refer to [Making API Calls](/guides/subscriptions-v2/quick-start) for more information. schemas: BillingRuleEntity: type: object title: '' properties: id: type: integer example: 1 readOnly: true shop_id: type: integer example: 1 readOnly: true subscription_group_id: type: integer example: 1 readOnly: true interval_number: type: integer example: 1 interval_type: type: string example: month enum: - custom - day - week - month - year interval_name: type: string example: Monthly maxLength: 255 week_type: type: string example: '' enum: - purchase_day - each - '' week_day: type: integer example: 0 description: Sets day of week when paired with week_type=each. Valid values are SU, MO, TU, WE, TH, FR, and SA. Can be comma separated list. month_type: type: string example: purchase_day enum: - purchase_day - each - on_the - '' month_day: type: string example: '' description: Sets the day of the month when combined with month_type=each. Numbers in range 1-31. Can be comma separated list of numbers. month_occurrence: type: string example: '' enum: - first - second - third - fourth - fifth - last - '' month_occurrence_day: type: string example: MO description: Sets day of week when paired with month_occurence=on_the. Valid values are SU, MO, TU, WE, TH, FR, SA, day, business_day, weekend_day. Can be comma separated list. year_type: type: string enum: - purchase_day - on_the - '' year_month: type: string example: '' description: Sets month of year when combined with year_type=on_the. Valid values between 1-12. Can be comma separated list. year_occurrence: type: string example: '' enum: - first - second - third - fourth - fifth - last - '' year_occurrence_day: type: string example: '' description: Sets day of week when paired with year_occurence. Valid values are SU, MO, TU, WE, TH, FR, SA, day, business_day, weekend_day. Can be comma separated list. billing_rule: type: string example: FREQ=MONTHLY created_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time updated_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time deleted_at: type: string example: null readOnly: true format: date-time nullable: true custom_billing_rule: type: string description: A custom RRULE for the subscription group buffer_days: type: integer minimum: 0 maximum: 365 buffer_time: type: string format: time example: '01:00:00' description: Time is in format HH:mm:ss Customers: properties: customers: type: array items: $ref: '#/components/schemas/CustomerEntity' type: object Customer: properties: customer: $ref: '#/components/schemas/CustomerEntity' type: object CustomerEntity: type: object required: - id - platform_id - cashier_public_id - first_name - last_name - phone - email - notes - addresses - default_address - subscription_summary - labels - created_at properties: id: description: The customer ID. type: integer readOnly: true example: 2 platform_id: description: The customer platform ID. type: string readOnly: true example: '123456790' cashier_public_id: type: string description: The public customer ID generated when using Bold Checkout, set to `null` otherwise. example: null nullable: true readOnly: true first_name: type: string description: The customer's first name. example: Jane last_name: type: string description: The customer's last name. example: Doe email: type: string description: The customer's email example: jane.doe@example.com phone: type: string description: The customer's phone number. For Shopify checkout users, [you can configure phone number requirements in the admin](/guides/subscriptions-v2/create-subscription#how-do-i-make-phone-numbers-optional-when-using-shopify-checkout). example: '12045551234' notes: type: string description: The customer's internal notes. This is applied as a note in the **Customer info** section of Bold Subscriptions admin. example: Loyal customer addresses: type: array items: $ref: '#/components/schemas/CustomerAddressEntity' readOnly: true default_address: description: The customer's default address. readOnly: true allOf: - $ref: '#/components/schemas/CustomerAddressEntity' subscription_summary: readOnly: true allOf: - $ref: '#/components/schemas/CustomerSubscriptionSummary' labels: type: array items: $ref: '#/components/schemas/CustomerLabel' readOnly: true created_at: $ref: '#/components/schemas/createdAt' CustomerSubscriptionSummary: type: object required: - bold_platform_customer_id - next_order_date - last_order_date - active_subscription_count - inactive_subscription_count - subscription_order_count - lifetime_value_usd description: Summary of the customer's subscriptions. properties: bold_platform_customer_id: type: integer description: The customer's ID. example: 2 readOnly: true next_order_date: type: string description: The cext order date and time for the subscription. example: '2020-01-20T18:00:00Z' readOnly: true last_order_date: type: string description: The most recent order date and time for a subscription. example: '2019-11-20T20:55:27Z' readOnly: true active_subscription_count: type: integer description: The number of active subscriptions. example: 2 readOnly: true inactive_subscription_count: type: integer description: The number of inactive subscriptions. example: 1 readOnly: true subscription_order_count: type: integer description: The number of subscription orders for this customer. Initial orders count toward this total. example: 5 readOnly: true lifetime_value_usd: type: number description: The total value of the order made by this customer in USD. example: 152.12 readOnly: true CustomerAddressEntity: type: object required: - id - shop_identifier - platform_id - customer_id - platform_type - platform_customer_id - first_name - last_name - company - phone - street1 - street2 - city - province - province_code - country - country_code - zip - is_default - address_use - address_source - created_at - updated_at - deleted_at properties: id: type: integer description: The address ID. readOnly: true example: 1 shop_identifier: type: string description: The platform shop identifier. readOnly: true example: '12345' platform_id: type: string description: The platform address identifier. readOnly: true example: '14' customer_id: type: integer description: The customer ID. readOnly: true example: 2 platform_type: type: string enum: - bigcommerce - commercetools - custom - shopify - woocommerce description: The e-commerce platform being used by the shop (might also be 'custom' for no specific e-commerce platform). readOnly: true example: shopify platform_customer_id: type: string readOnly: true description: The ID of the customer on the platform. example: '35' first_name: type: string description: The customer's first name. example: John last_name: type: string description: The customer's last name(s). example: Doe company: type: string description: The customer's company name. example: Example Company phone: type: string description: The customer's phone number. example: 123-456-7890 street1: type: string description: The customer's street address (street name and number). example: 123 example st. street2: type: string description: The address complement (suite number, unit number, etc.). example: '101' city: type: string description: The customer's city. example: Toronto province: type: string description: The customer's province or state, as applicable. Can be an empty string in case the address has no state/province. example: Ontario province_code: type: string description: The customer's province or state code (usually 2 characters), as applicable. Can be an empty string in case the address has no state/province. example: 'ON' country: type: string description: The customer's country name. example: Canada country_code: type: string description: 'The customer''s alpha 2 country code, according to ISO 3166-1 (reference: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).' example: CA zip: type: string description: The customer's postal code. example: M5V 3L9 is_default: type: boolean description: Defines if this address should be considered the default one for the customer. example: true address_use: type: string nullable: true description: The address usage (billing, shipping). Only set for WooCommerce, `null` otherwise. example: billing address_source: type: string description: The address source. enum: - platform - bold readOnly: true example: platform created_at: $ref: '#/components/schemas/createdAt' updated_at: $ref: '#/components/schemas/updatedAt' deleted_at: $ref: '#/components/schemas/deletedAt' UpdateCustomerAddressEntity: type: object required: - first_name - last_name - phone - street1 - city - province - province_code - country - country_code - zip properties: first_name: type: string description: Customer's first name. example: John last_name: type: string description: Customer's last name(s). example: Doe company: type: string description: Customer's company name. example: Example Company phone: type: string description: Customer's phone number. example: 123-456-7890 street1: type: string description: Customer's street address (street name and number). example: 123 example st. street2: type: string description: Address complement (suite number, unit number, etc.). example: '101' city: type: string description: Customer's city. example: Toronto province: type: string description: Customer's province or state, as applicable. Can be an empty string in case the address has no state/province. example: Ontario province_code: type: string description: Customer's province or state code (usually 2 characters), as applicable. If the address has no state/province, leave empty. example: 'ON' country: type: string description: Customer's country name. example: Canada country_code: type: string description: 'Customer''s alpha 2 country code, according to ISO 3166-1 (reference: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).' example: CA zip: type: string description: Customer's postal code. example: M5V 3L9 is_default: type: boolean description: Indicates whether this address should be considered the default one for the customer. example: true address_use: type: string description: Address usage (billing, shipping). Only set for WooCommerce. CustomerLabel: type: object description: The label assigned to a customer. required: - id - name - created_at - updated_at - deleted_at properties: id: type: integer description: The customer label ID. example: 12 readOnly: true customer_id: type: integer description: The customer ID. example: 21 readOnly: true name: type: string description: The content of the label. example: bsub_subscription_active created_at: $ref: '#/components/schemas/createdAt' updated_at: $ref: '#/components/schemas/updatedAt' deleted_at: readOnly: true allOf: - $ref: '#/components/schemas/deletedAt' FutureOrders: properties: future_orders: type: array items: $ref: '#/components/schemas/FutureOrderEntity' pagination: $ref: '#/components/schemas/FutureOrdersCursorPagination' type: object UnauthenticatedResponse: type: object properties: error: type: string description: The error summary. example: invalid_request error_description: type: string description: The detailed error message. example: The access token is missing example: error: invalid_request error_description: The access token is missing FutureOrderEntity: properties: id: type: string description: The unique identifier of the future order in the format `{subscription_id}-{order_date}`, where `{order_date}` uses [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). example: 53236-2024-05-21T08:00:00Z date: type: string description: The date and time of the future order, in [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). example: '2024-05-21T08:00:00Z' bold_customer_id: type: integer description: The ID for the customer associated with the future order. example: 1697912 bold_platform_subscription_id: type: integer description: The ID of the subscription associated with the future order. example: 4712349 currency: type: string description: The currency used for the future order, in [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) format. example: USD order_count: type: integer description: 'The number ("n") indicates the future order will be the nth order for the subscription. The value will be `null` if the future order is skipped. Example: `order_count: 6` means the future order is the 6th order for the subscription.' example: 6 nullable: true subscription_data: type: object description: Details on the subscription associated with the future order. properties: id: type: integer description: The ID of the subscription associated with the future order. example: 4712349 order_count: type: integer description: The number of orders currently processed by the subscription associated with the future order. example: 2 discount_code: type: string description: The discount code currently on the subscription. The value is an empty string `""` if no discount is applied. example: BOXINGDAYSUB order_rrule: type: string description: An RRULE describing how frequently orders are processed for the subscription. Learn more about [RRULEs](https://support.boldcommerce.com/hc/en-us/articles/360045174132-Use-RRULES-in-Bold-Subscriptions). example: |- DTSTART:20210521T080000Z RRULE:FREQ=MONTHLY base_currency: type: string description: The base currency of the subscription, in [ISO 4217 format](https://www.iso.org/iso-4217-currency-codes.html). This aligns with the store's platform configuration for primary currency when the subscription was placed, unless later modified. example: CAD charged_currency: type: string description: The currency the customer is charged in, in [ISO 4217 format](https://www.iso.org/iso-4217-currency-codes.html). example: USD base_to_charged_exchange_rate: type: number description: The exchange rate from the subscription's base currency to the charged currency. example: 0.79 placed_at: type: string description: The date and time the subscription was placed by the customer, in [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). For programmatically created or migrated subscriptions this value may be `null`. nullable: true example: '2024-02-21T08:00:00Z' is_skipped: type: boolean description: Indicates if the future order is set to be skipped. example: false customer: $ref: '#/components/schemas/Customer' adjustments: type: array description: The list of subscription adjustments with target "order" to apply to the future order. `adjustments` is `null` if there are no adjustments to return. nullable: true minItems: 0 items: $ref: '#/components/schemas/SubscriptionAdjustment' line_items: type: array minItems: 0 description: The line items in the future order. items: $ref: '#/components/schemas/FutureOrderLineItemEntity' shipping_lines: type: array description: |- The shipping lines for the future order. **Note:** Shipping lines may differ at time of processing. List available shipping lines with the Checkout Frontend [List Shipping Lines endpoint](https://developer.boldcommerce.com/default/api/checkout#tag/Shipping-Lines/operation/ListShippingLines). items: $ref: '#/components/schemas/ShippingLineEntity' billing_address: $ref: '#/components/schemas/CustomerAddressEntity' shipping_address: type: object nullable: true allOf: - $ref: '#/components/schemas/CustomerAddressEntity' type: object readOnly: true FutureOrderLineItemEntity: type: object properties: future_order_id: type: string description: The unique identifier of the future order in the format `{subscription_id}-{order_date}`, where `{order_date}` uses [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). example: 53236-2024-05-21T08:00:00Z bold_platform_subscription_id: type: integer description: The ID of the subscription associated with this line item. example: 4712349 bold_platform_subscription_line_item_id: type: integer description: The ID of the subscription line item. If a line item is created from a future adjustment, `bold_subscription_line_item_id` is set to `null`. example: 643723 nullable: true adjustment_id: type: integer description: The ID of the subscription adjustment adding this line item to the order, if applicable. example: 36217 nullable: true platform_id: type: string description: When applicable, the unique ID of the line item on the platform subscription. example: '6434329530' nullable: true platform_product_id: type: string description: The platform-specific product ID. example: '478723258026' platform_variant_id: type: string description: The platform-specific variant ID. example: '92183258642' title: type: string description: The title of the line item including both product and variant names. example: Roaster's Choice - 2lb product_name: type: string description: The name of the product. example: Roaster's Choice variant_name: type: string description: The name of the variant. example: 2lb sku: type: string description: The SKU of the product variant. example: RC-2LB url: type: string description: The URL of the product on the storefront. example: /products/roasters-choice image: type: string description: The platform image URL for the line item. example: https://cdn.shopify.com/s/files/1/6332/09823/products/roasters-choice.png?v=1555362485 quantity: type: integer description: The quantity of the line item in the future order. example: 3 price: type: integer description: 'The price of this line item within the subscription, in the base unit (e.g., cents) of the `charged_currency` for this subscription. Example: a value of `1000` in a USD currency corresponds to a $10.00 USD per-unit price on the line item.' example: 1000 requires_shipping: type: boolean description: Indicates whether this line item is subject to applicable shipping fees. example: true grams: type: integer description: The weight of a single unit of the line item in grams. example: 1043 weight: type: number description: The weight of a single unit of the line item, measured in `weight_unit`. example: 2.3 weight_unit: type: string description: Indicates the unit of measurement reflected by the `weight` field. example: lb taxable: type: boolean description: Indicates whether the line item is subject to applicable taxes. example: true line_item_attributes: type: array minItems: 0 items: $ref: '#/components/schemas/LineItemAttributeEntity' prepaid_metadata: nullable: true type: object allOf: - $ref: '#/components/schemas/FutureOrderLineItemPrepaidMetadataEntity' subscription_group_id: type: integer description: The ID of the subscription group that contains this line item's product. example: 36236 nullable: true subscription_group_billing_rules_id: type: integer description: The ID of the subscription group billing rule associated with the subscription's order frequency. example: 78365 nullable: true discounts: type: array minItems: 0 items: $ref: '#/components/schemas/LineItemDiscountEntity' Intervals: properties: intervals: type: array items: $ref: '#/components/schemas/IntervalEntity' type: object IntervalEntity: properties: interval_number: type: integer example: 1 interval_type: type: string enum: - month - week - day - year - custom example: month week_type: type: string enum: - '' - purchase_day - each example: each week_day: type: string enum: - '' - FR - MO - SA - SU - TH - TU - WE example: MO month_type: type: string enum: - '' - purchase_day - each - on_the example: purchase_day month_day: type: string example: '15' month_occurrence: type: string enum: - last - second - first - fourth - third - '' example: first month_occurrence_day: type: string enum: - '' - FR - MO - SA - SU - TH - TU - WE - business_day example: MO year_type: type: string enum: - '' - purchase_day - on_the example: on_the year_month: type: string example: '6' year_occurrence: type: string example: first year_occurrence_day: type: string enum: - '' - FR - MO - SA - SU - TH - TU - WE example: FR interval_name: type: string example: Monthly id: type: integer readOnly: true example: 1 billing_rule: type: string example: DTSTART:20191120T205526Z\nRRULE:FREQ=MONTHLY type: object readOnly: true LineItemEntity: type: object title: '' properties: id: type: integer example: 1 nullable: true subscription_id: type: integer example: 1 nullable: true platform_id: type: string example: ABC123 nullable: true platform_product_id: type: string example: '1357908642' nullable: true platform_variant_id: type: string example: '2468097531' nullable: true subscription_group_id: type: integer example: 1 nullable: true subscription_group_billing_rules_id: type: integer example: 1 nullable: true title: type: string example: Monthly Expansion Pack product_name: type: string example: Monthly Expansion Pack nullable: true variant_name: type: string example: Default Title nullable: true sku: type: string example: SKU-113-Red url: type: string example: https://example-store.example.com/monthly-expansion-pack image: type: string example: '' nullable: true quantity: type: integer example: 1 price: type: integer example: 3500 price_charged: type: integer example: 3200 nullable: true discounted_price: type: integer example: 3200 discounted_price_charged: type: integer example: 3200 full_price: type: integer example: 3200 nullable: true full_price_charged: type: integer example: 3200 nullable: true requires_shipping: type: boolean example: false grams: type: integer example: 2200 weight: type: number example: 2.2 weight_unit: type: string example: kg taxable: type: boolean example: true discounts: type: array items: $ref: '#/components/schemas/LineItemDiscountEntity' readOnly: true prepaid_metadata: type: object required: - id - line_item_id - prepaid_duration - current_recurrence_count - prepaid_continue nullable: true properties: id: type: integer example: 1 nullable: true line_item_id: type: integer example: 2 nullable: true prepaid_duration: type: integer example: 2 current_recurrence_count: type: integer example: 2 prepaid_continue: type: string enum: - no_continue - as_prepaid - as_standard line_item_attributes: type: array items: $ref: '#/components/schemas/LineItemAttributeEntity' created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true nullable: true required: - id - subscription_id - platform_id - platform_product_id - platform_variant_id - subscription_group_id - subscription_group_billing_rules_id - title - product_name - variant_name - sku - url - image - quantity - price - price_charged - discounted_price - discounted_price_charged - full_price - requires_shipping - grams - weight - weight_unit - taxable - discounts - prepaid_metadata - created_at - updated_at readOnly: true UpdateLineItemEntity: type: object title: '' properties: id: type: integer example: 1 nullable: true subscription_id: type: integer example: 1 nullable: true platform_id: type: string example: ABC123 platform_product_id: type: string example: '1357908642' nullable: true platform_variant_id: type: string example: '2468097531' nullable: true subscription_group_id: type: integer example: 1 subscription_group_billing_rules_id: type: integer example: 1 nullable: true title: type: string example: Monthly Expansion Pack product_name: example: null nullable: true description: Always returns `null`. variant_name: example: null nullable: true description: Always returns `null`. sku: type: string example: SKU-113-Red url: type: string example: https://example-store.example.com/monthly-expansion-pack image: type: string example: '' quantity: type: integer example: 1 price: type: integer example: 3500 price_charged: type: integer example: 3200 nullable: true discounted_price: type: integer example: 3200 discounted_price_charged: type: integer example: 3200 full_price: type: integer example: 3200 full_price_charged: type: integer example: 3200 requires_shipping: type: boolean example: false grams: type: integer example: 2200 weight: type: number example: 2.2 weight_unit: type: string example: kg taxable: type: boolean example: true discounts: type: array items: $ref: '#/components/schemas/LineItemDiscountEntity' readOnly: true prepaid_metadata: type: object required: - id - line_item_id - prepaid_duration - current_recurrence_count - prepaid_continue nullable: true properties: id: type: integer example: 1 nullable: true line_item_id: type: integer example: 2 nullable: true prepaid_duration: type: integer example: 2 current_recurrence_count: type: integer example: 2 prepaid_continue: type: string enum: - no_continue - as_prepaid - as_standard line_item_attributes: type: array items: $ref: '#/components/schemas/LineItemAttributeEntity' created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true required: - id - subscription_id - platform_id - platform_product_id - platform_variant_id - subscription_group_id - subscription_group_billing_rules_id - title - product_name - variant_name - sku - url - image - quantity - price - price_charged - discounted_price - discounted_price_charged - full_price - requires_shipping - grams - weight - weight_unit - taxable - discounts - prepaid_metadata - created_at - updated_at readOnly: true LineItemAttributeEntity: title: LineItemAttributeEntity type: object description: This represents a custom field that can be defined and used to store complementary information about a subscription line item. properties: name: type: string example: size_preference description: The name of the custom field/attribute, up to 250 characters. value: type: string example: XL description: The content of the custom field/attribute. created_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this line item attribute was created. example: '2021-01-17T20:30:40Z' readOnly: true updated_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this line item attribute was last updated. The value is the same as the `created_at` value if the line item attribute has never been updated. example: '2021-01-17T20:30:40Z' readOnly: true subscription_id: description: The ID of the subscription associated to this line item attribute. type: integer readOnly: true example: 435989 line_item_id: description: The ID of the subscription line item this line item attribute belongs to. type: integer readOnly: true example: 45734 PrepaidMetadataEntity: type: object properties: id: description: The ID of the prepaid metadata. type: integer example: 1 line_item_id: description: The ID of the subscription line item this prepaid metadata belongs to. type: integer example: 1 prepaid_continue: description: |- 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. type: string enum: - no_continue - as_prepaid - as_standard example: as_prepaid prepaid_duration: description: The number of subscription recurrences that have been prepaid. type: integer example: 6 current_recurrence_count: description: The number of subscription recurrences that have occurred. type: integer example: 6 required: - prepaid_continue - prepaid_duration - current_recurrence_count FutureOrderLineItemPrepaidMetadataEntity: type: object properties: prepaid_continue: description: |- 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. type: string enum: - no_continue - as_prepaid - as_standard example: as_prepaid prepaid_duration: description: The number of subscription recurrences that get prepaid for in a cycle. type: integer example: 6 recurrence_count: description: Indicates which recurrence of the prepaid cycle the future order will be. type: integer example: 1 requires_payment: description: Indicates whether the line item and associated subscription will be charged for a full prepaid cycle. When payment is required, the line item price and shipping line prices of the future order will be multiplied by the appropriate prepaid duration. When payment is required and no other standard line items are present then prices will be 0. type: boolean example: true LineItemDiscountEntity: type: object properties: id: type: integer description: The ID of the line item discount. example: 1 nullable: true subscription_line_item_id: type: integer description: The ID of the subscription line item the discount belongs to. example: 1 nullable: true shop_id: type: integer description: The ID of the shop. example: 5 full_price: type: integer description: The price of the subscription line item without this discount applied. example: 5 nullable: true discount_type: type: string description: The type of discount being applied to the subscription line item. enum: - percentage - fixed - no_discount example: percentage percentage_value: type: number description: The percent discount to apply to the line item price in a range of 0 - 100. Only applied when the value for `discount_type` is `percentage`. For example, a value of `12.5` will discount the line item by 12.5%. example: 10 fixed_value: type: integer description: The discount amount in base currency units (e.g. cents). Only applied when the value for `discount_type` is `fixed`. For example, a value of `575` on a subscription with a base currency of USD will discount the line item by $5.75 USD. example: 0 fixed_value_charged: type: integer description: The discount amount in base currency units (e.g. cents) of the subscription's `charged_currency`. Only applied when the value for `discount_type` is `fixed`. This value is derived from the `fixed_value` and the subscription's currency properties. For example, with a `fixed_value` of 575, a base currency of USD, a charged currency of CAD, and an exchange rate of 1.5, this value would be 575 * 1.5 = `863`. example: 0 description: type: string description: A description of the discount to show to the customer. example: Subscription discount (10%) for Monthly Expansion Pack created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this discount added to the subscription line item. nullable: true readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this discount was last updated. The value is the same as the `created_at` value if the discount has never been updated. nullable: true readOnly: true deleted_at: type: string example: '2019-11-20T20:31:55Z' format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this discount was removed from the subscription line item. The value is null if the discount has never been deleted. nullable: true readOnly: true required: - id - subscription_line_item_id - shop_id - full_price - discount_type - percentage_value - fixed_value - fixed_value_charged - description - created_at - updated_at - deleted_at readOnly: true OrderEntity: type: object x-examples: {} title: '' properties: id: type: integer example: 185490 platform_id: type: integer example: 1 platform_customer_id: type: integer example: 123 shop_identifier: type: string example: zya0kzb8hu line_items: type: array items: $ref: '#/components/schemas/LineItemEntity' billing_address: nullable: true description: Orders that were deleted from the platform won't have address information available. type: object allOf: - $ref: '#/components/schemas/CustomerAddressEntity' shipping_addresses: nullable: true description: Orders that were deleted from the platform won't have address information available. type: array items: $ref: '#/components/schemas/CustomerAddressEntity' subtotal: type: integer example: 1337 subtotal_charged: type: integer example: 1337 subtotal_tax: type: integer example: 144 subtotal_tax_charged: type: integer example: 144 shipping_subtotal: example: 1000 type: integer shipping_subtotal_charged: type: integer example: 1000 shipping_tax: example: 0 type: integer shipping_tax_charged: example: 0 type: integer total: example: 2204 type: integer total_charged: example: 2204 type: integer total_tax: example: 144 type: integer total_tax_charged: example: 144 type: integer fulfillment_status: type: string example: pending source: type: string payment_method: type: string example: Shopify Payments payment_method_details: nullable: true type: object allOf: - $ref: '#/components/schemas/PaymentMethodEntity' shipping_method: type: string example: Subscription shipping shipping_rates: type: array items: type: object properties: id: type: integer nullable: true bold_subscription_id: type: number nullable: true name: type: string code: type: string nullable: true price: type: integer price_charged: type: integer nullable: true value: type: integer value_charged: type: integer nullable: true tag: type: string nullable: true hash: type: string nullable: true required: - id - bold_subscription_id - name - code - price - price_charged - value - value_charged - tag - hash tax_lines: type: array items: type: object properties: amount: type: integer amount_charged: type: integer name: type: string nullable: true rate: type: number nullable: true required: - amount - amount_charged - name - rate discounts: type: array items: type: object properties: discount_percentage: type: integer example: 10 nullable: true discount_type: type: string enum: - percentage - fixed - no_discount example: percentage nullable: true text: type: string example: 10PERCENTOFF nullable: true readOnly: true value: type: integer value_charged: type: integer required: - discount_percentage - discount_type - text - value - value_charged order_number: type: integer example: 0 currency: type: string example: CAD currency_charged: type: string currency_format: type: string currency_format_charged: type: string exchange_rate: type: number nullable: true test: type: boolean example: false url: type: string example: https://example-store.example.com/account.php?action=view_order&order_id=1 updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true placed_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true deleted_at: type: string example: '2021-07-09T18:13:27Z' format: date-time nullable: true readOnly: true subscription_id: type: integer example: 5266 required: - id - platform_id - platform_customer_id - shop_identifier - line_items - billing_address - shipping_addresses - subtotal - subtotal_charged - subtotal_tax - subtotal_tax_charged - shipping_subtotal - shipping_subtotal_charged - shipping_tax - shipping_tax_charged - total - total_charged - total_tax - total_tax_charged - fulfillment_status - source - payment_method - payment_method_details - shipping_method - shipping_rates - tax_lines - discounts - order_number - currency - currency_charged - currency_format - currency_format_charged - exchange_rate - test - url - updated_at - created_at - placed_at - deleted_at - subscription_id readOnly: true PaymentMethods: properties: payment_methods: type: array items: $ref: '#/components/schemas/PaymentMethodEntity' type: object PaymentMethod: properties: payment_method: $ref: '#/components/schemas/PaymentMethodEntity' type: object PaymentMethodEntity: type: object properties: type: type: string example: credit_card enum: - credit_card - paypal - shop_pay name: type: string example: John Doe nullable: true description: Customer's name billing_address: type: object nullable: true description: Customer's billing address. properties: street: type: string example: 123 Main Street description: The customer's street address. nullable: true city: type: string example: Toronto description: The customer's city. nullable: true province: type: string example: Ontario description: The customer's province or state, as applicable. nullable: true country: type: string example: Canada description: The customer's country name. nullable: true zip: type: string example: H0H 0H0 description: The customer's postal code. nullable: true public_id: type: string example: jik1w6HrCn17CxXPDkWhtgyqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG nullable: true update_method: type: string example: trigger_email enum: - trigger_email - embedded - url nullable: true cc_type: type: string example: Visa nullable: true expiration: type: object required: - date - timezone_type - timezone nullable: true properties: date: type: string example: 2020-5 nullable: true timezone_type: type: string nullable: true timezone: type: string example: UTC nullable: true last_four: type: string example: '1111' nullable: true is_default: type: boolean example: true nullable: true paypal_email: type: string example: customer@example.com format: email nullable: true update_url: type: object required: - url - expiry nullable: true properties: url: type: string format: uri expiry: type: string format: date-time embed_url: type: object nullable: true properties: url: type: string format: uri expiry: type: string format: date-time nullable: true required: - url - expiry required: - type - public_id - update_method - cc_type - expiration - last_four - is_default - paypal_email - update_url readOnly: true SelectionOptionEntity: type: object description: '' properties: id: type: integer example: 1 readOnly: true shop_id: type: integer example: 1 readOnly: true subscription_group_id: type: integer example: 1 readOnly: true platform_entity_id: type: string example: '1357908642' created_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time updated_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time deleted_at: type: string example: null readOnly: true format: date-time nullable: true entity_id: type: integer example: 1472540 readOnly: true bold_platform_entity_id: type: integer example: 1234 ShippingLineEntity: type: object description: A shipping line for a subscription. properties: id: type: integer description: The ID of the shipping line. nullable: true readOnly: true example: 36217 name: type: string description: The name of the shipping line. example: Standard Shipping readOnly: true code: type: string description: The code of the shipping line. example: Standard Shipping readOnly: true price: type: integer description: The price of the shipping line, in base units (e.g., cents) of the `base_currency` of the associated subscription. For example, a value of `1000` on a subscription with a base currency of USD corresponds to a $10.00 USD shipping line price. example: 1000 readOnly: true value: type: integer description: The price of the shipping line, in base units (e.g., cents) of the `base_currency` of the associated subscription. For example, a value of `1000` on a subscription with a base currency of USD corresponds to a $10.00 USD shipping line price. example: 1000 readOnly: true value_charged: type: integer description: The price of the shipping line, in base units (e.g., cents) of the `charged_currency` of the associated subscription. For example, a value of `1000` on a subscription with a charged currency of CAD corresponds to a $10.00 CAD shipping line price. example: 1000 nullable: true readOnly: true tag: type: string example: Shipping nullable: true readOnly: true created_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this shipping line was created. example: '2019-10-20T20:31:55Z' nullable: true readOnly: true updated_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this shipping line was last updated. The value is the same as the `created_at` value if the shipping line has never been updated. example: '2019-11-20T20:31:55Z' nullable: true readOnly: true subscription_id: type: integer description: The ID of the subscription the shipping line belongs to. example: 1 nullable: true readOnly: true required: - id - name - code - price - value - value_charged - tag - created_at - updated_at - subscription_id readOnly: true Shop: properties: shop: $ref: '#/components/schemas/ShopEntity' type: object ShopEntity: type: object title: '' properties: id: type: integer example: 1 readOnly: true shop_domain: type: string example: store-abc123def456.example.com readOnly: true custom_domain: type: string example: example-store.example.com readOnly: true shop_identifer: type: string example: zya0kzb8hu7ji readOnly: true platform_type: type: string example: bigcommerce enum: - bigcommerce - shopify - woocommerce - commercetools - custom readOnly: true timezone: type: string example: Europe/London readOnly: true currency: type: string example: CAD readOnly: true currency_format: type: string example: ${{amount}} readOnly: true shop_owner: type: string example: John Doe readOnly: true admin_email: type: string example: john.doe@example.com readOnly: true pii_redacted_at: type: string example: '2019-11-20T20:31:55Z' format: date-time nullable: true readOnly: true created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true deleted_at: type: string example: '2019-11-20T20:31:55Z' format: date-time nullable: true readOnly: true required: - id - shop_domain - custom_domain - shop_identifer - platform_type - timezone - currency - currency_format - shop_owner - admin_email - pii_redacted_at - created_at - updated_at - deleted_at StandardPaginationEntity: properties: total: type: integer readOnly: true example: 2 count: type: integer readOnly: true example: 2 per_page: type: integer readOnly: true example: 10 total_pages: type: integer readOnly: true example: 1 current_page: type: integer readOnly: true example: 1 type: object readOnly: true Subscriptions: type: object properties: subscriptions: type: array items: $ref: '#/components/schemas/SubscriptionEntity' pagination: $ref: '#/components/schemas/StandardPaginationEntity' ListSubscriptions: type: object title: ListSubscriptions properties: subscriptions: type: array items: $ref: '#/components/schemas/SubscriptionEntity' pagination: $ref: '#/components/schemas/CursorPagination' Subscription: type: object properties: subscription: $ref: '#/components/schemas/SubscriptionEntity' SubscriptionUpdateLineItems: type: object properties: subscription: $ref: '#/components/schemas/SubscriptionUpdateLineItemsEntity' CreateLineItemsResponse: type: object properties: line_items: type: array items: $ref: '#/components/schemas/LineItemEntity' CreateSubscriptionError422: type: object properties: errors: type: array description: An array of various errors. items: type: object properties: Message: type: string example: The next order datetime must be a string. Field: type: string example: subscription.next_order_datetime. Type: type: string example: string idempotency_key: type: string description: The idempotency key of this subscription creation request. Learn more about [setting an idempotency key](/guides/subscriptions-v2/create-subscription#choosing-an-idempotency-key). example: legacy-id-1234 current_subscription_creation_step: type: string description: A string indicating the step of subscription creation during which the error occurred. example: customer_billing_address_creation subscription_creation_log_id: type: integer description: An integer ID representing the subscription creation log tied to the request. This ID persists across requests that have the same idempotency key. If you require further troubleshooting, provide this ID to [Bold Support](https://support.boldcommerce.com/hc/en-us/requests/new?ticket_form_id=1900000280347). example: 82372 SubscriptionEntity: allOf: - type: object x-examples: {} properties: id: type: integer example: 1 readOnly: true external_id: type: string nullable: true customer: example: 'null' shop_id: type: integer example: 1 readOnly: true next_order_datetime: type: string example: '2020-01-20T18:00:00Z' next_payment_datetime: type: string example: '2020-01-20T18:00:00Z' next_processing_datetime: type: string example: '2020-01-20T18:00:00Z' subscription_status: type: string enum: - active - inactive - paused - scheduled - processing - app_uninstalled - waiting_sca_authorization example: active status_changed_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true sca_url: type: string example: https://bank.com/pCkWhtgQQVM8W/sca nullable: true readOnly: true payment_method_token: type: string example: jik1w6HrCn17CxXPcKwHTGqqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG payment_gateway_public_id: type: string example: jik1w6HrCn17CxXPcKwHTGqqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG nullable: true payment_rrule: type: string example: DTSTART:20200120T180000Z\nRRULE:FREQ=MONTHLY\nEXDATE:20200220T180000Z payment_rrule_text: type: string example: Monthly nullable: true order_rrule: type: string example: DTSTART:20200120T180000Z\nRRULE:FREQ=MONTHLY\nEXDATE:20200220T180000Z order_rrule_text: type: string example: Monthly nullable: true last_payment_datetime: type: string example: '2019-11-20T20:55:26Z' nullable: true last_order_datetime: type: string example: '2019-11-20T20:55:26Z' nullable: true last_processed_datetime: type: string example: '2019-11-20T20:55:26Z' nullable: true current_retries: type: integer example: 3 charged_currency: type: string example: CAD base_to_charged_exchange_rate: type: integer example: 1 base_currency: type: string example: CAD line_items: type: array items: $ref: '#/components/schemas/LineItemEntity' readOnly: true shipping_lines: type: array nullable: true items: $ref: '#/components/schemas/ShippingLineEntity' readOnly: true billing_address: $ref: '#/components/schemas/CustomerAddressEntity' shipping_address: nullable: true type: object allOf: - $ref: '#/components/schemas/CustomerAddressEntity' idempotency_key: type: string example: JwGdN55C4g1z5FXRO8Hp21CMxUxKyo6VcGSf3cUsjCgNyTtoeZcIsGM1We4p7pCe-0 placed_at: type: string example: '2012-11-20T20:31:55Z' format: data-time nullable: true created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true percent_discount: type: number example: 10 nullable: true readOnly: true discount_code: type: string example: DISCOUNTCODE readOnly: true customer_id: type: integer example: 1697912 readOnly: true billing_address_id: type: integer example: 11697812 shipping_address_id: type: integer example: 11697812 orders_processed: type: integer example: 1 nullable: true last_failure_code: type: string example: card_expired description: This code may help to identify the type of the error. nullable: true 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 last_failure_details: type: object nullable: true description: Default error messages for the last_failure_code field required: - message properties: message: type: string description: Error message example: The order couldn't process because the card was declined. nullable: false last_failure_reason: type: string example: credit_card description: The reason for the failure nullable: true enum: - credit_card - gateway - cashier - platform - inventory - other - $ref: '#/components/schemas/SubscriptionNotesEntity' - $ref: '#/components/schemas/SubscriptionOrderCountEntity' required: - id - external_id - customer - shop_id - next_order_datetime - next_payment_datetime - next_processing_datetime - subscription_status - status_changed_at - payment_method_token - payment_gateway_public_id - payment_rrule - payment_rrule_text - order_rrule - order_rrule_text - last_payment_datetime - last_order_datetime - last_processed_datetime - current_retries - charged_currency - base_to_charged_exchange_rate - base_currency - idempotency_key - created_at - updated_at - percent_discount - customer_id - billing_address_id - shipping_address_id - note - order_note SubscriptionOrderCountEntity: properties: order_count: description: The number of orders created for the subscription. type: integer example: 1 SubscriptionNotesEntity: properties: note: description: 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. type: string example: Staff note nullable: true order_note: description: 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. type: string example: Customer note nullable: true CreateSubscriptionEntity: type: object properties: customer: type: object required: - first_name - last_name - email properties: first_name: type: string description: The customer's first name example: Jane last_name: type: string description: The customer's last name example: Doe email: type: string description: The customer's email example: jane.doe@example.com phone: type: string description: The customer's phone number. For Shopify checkout users, [you can configure phone number requirements in the admin](/guides/subscriptions-v2/create-subscription#how-do-i-make-phone-numbers-optional-when-using-shopify-checkout). example: '12045551234' notes: type: string description: Internal notes about the customer. This is applied as a note in the Customer info section of Bold Subscriptions admin. example: Loyal customer subscription: allOf: - type: object required: - idempotency_key - next_order_datetime - subscription_status - order_rrule - charged_currency - base_to_charged_exchange_rate - base_currency - line_items - billing_address - shipping_address - payment_details properties: idempotency_key: type: string description: The idempotency key of this subscription creation request. Learn more about [setting an idempotency key](/guides/subscriptions-v2/create-subscription#choosing-an-idempotency-key). example: legacy-id-21425 next_order_datetime: type: string description: The date and time of the next order, in [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). example: '2021-05-21T08:00:00Z' last_order_datetime: type: string description: If migrating subscriptions from another application, the date and time of the customer's last order on the legacy system, in [RFC 3339 format](https://www.ietf.org/rfc/rfc3339.txt). example: '2021-04-21T08:00:00Z' subscription_status: type: string description: The status of the subscription. enum: - active - inactive - paused order_rrule: type: string description: An RRULE describing how frequently to process orders for the subscription. Learn more about [RRULEs](https://support.boldcommerce.com/hc/en-us/articles/360045174132-Use-RRULES-in-Bold-Subscriptions). example: |- DTSTART;TZID=America/New_York:20240425T000000Z RRULE:FREQ=MONTHLY base_currency: type: string description: The base currency of your store, in [ISO 4217 format](https://www.iso.org/iso-4217-currency-codes.html). This should align with your store's platform configuration. example: CAD charged_currency: type: string description: The currency to charge the customer with, in [ISO 4217 format](https://www.iso.org/iso-4217-currency-codes.html). example: USD base_to_charged_exchange_rate: type: number description: The exchange rate from your base currency to the charged currency. example: 0.79 line_items: type: array description: An array of line items to be added to the subscription. items: type: object required: - platform_product_id - platform_variant_id - quantity - price - subscription_group_id properties: platform_product_id: type: string description: The ID of the product on your platform. Learn more about [finding platform product IDs](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-platform_product_id-and-platform_variant_id-for-a-line-item). example: '1578934692' platform_variant_id: type: string description: 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](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-platform_product_id-and-platform_variant_id-for-a-line-item). example: '975285185' quantity: type: number description: The quantity of this line item within the subscription. example: 2 price: type: number description: Price in the base unit (e.g., cents) of the `base_currency` for this subscription. For example, a value of `1000` in a USD currency corresponds to a $10.00 per-unit price on the line item. example: 1000 subscription_group_id: type: number description: The ID of the subscription group that contains this product, found in the Subscriptions 2 admin. Learn more about [finding subscription group IDs](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-subscription_group_id-for-a-line-item). example: 123 billing_address: $ref: '#/components/schemas/CreateAddressEntity' shipping_address: $ref: '#/components/schemas/CreateAddressEntity' external_id: type: string description: If applicable, the ID of the subscription on its previous system. Recommended for subscriptions being migrated from legacy subscription apps. example: legacy-id-135798642 placed_at: type: string format: date-time description: The date the subscription was originally placed. Recommended for subscriptions being migrated from legacy subscription apps. example: '2012-05-21T08:00:00Z' nullable: true payment_details: type: object required: - gateway_name - gateway_customer_id description: The payment details used for processing orders. properties: gateway_name: type: string description: A string indicating the payment gateway being used. Learn more about [finding the gateway name](/guides/subscriptions-v2/create-subscription#how-do-i-find-payment-gateway-information-for-the-paymentdetails-object). example: Stripe Default Name gateway_customer_id: type: string description: A string that is used to associate a customer record with the corresponding customer from the payment gateway. Learn more about [finding the gateway customer ID](/guides/subscriptions-v2/create-subscription#how-do-i-find-payment-gateway-information-for-the-paymentdetails-object). example: cus_123456789 gateway_payment_id: type: string description: For Bold Checkout, this field is unused. For Shopify Checkout, this field is optional. It is used in combination with the `gateway_customer_id` to create a Shopify payment method that references the particular payment method associated with this ID. Learn more about [finding the gateway payment ID](/guides/subscriptions-v2/create-subscription#how-do-i-find-payment-gateway-information-for-the-paymentdetails-object). example: card_123456 discount_code: type: string description: Supported for Bold Checkout through the "Shopify Discount Connector" Marketplace plugin. Supported for Shopify checkout by default. example: DISCOUNTCODE nullable: true - $ref: '#/components/schemas/SubscriptionNotesEntity' - $ref: '#/components/schemas/SubscriptionOrderCountEntity' CreateAddressEntity: description: Address payload for the create endpoint. type: object required: - first_name - last_name - street1 - street2 - city - country - country_code properties: first_name: type: string description: The customer's first name. example: Jane last_name: type: string description: The customer's last name. example: Doe company: type: string description: The customer's company. example: Bold Commerce phone: type: string description: The customer's phone number. For Shopify checkout users, [you can configure phone number requirements in the admin](/guides/subscriptions-v2/create-subscription#how-do-i-make-phone-numbers-optional-when-using-shopify-checkout). example: '12045551234' street1: type: string description: The customer's address 1. example: 123 Alphabet St. street2: type: string description: The customer's address 2. example: '101' city: type: string description: The customer's city. example: Austin province: type: string description: The full written name of the province or state (e.g., Ontario). Required only for countries that have provinces if `province_code` is not provided. example: Texas province_code: type: string description: The short-form code representing the province or state (e.g., ON for Ontario), in [ISO 3166 format](https://www.iso.org/iso-3166-country-codes.html). Required only for countries that have provinces/states, and if `province` is not already provided. example: TX country: type: string description: The full written name of the country. Required if `'country_code'` is not already provided. example: United States country_code: type: string description: The short-form code representing the country, in [ISO 3166 format](https://www.iso.org/iso-3166-country-codes.html). Required if `country` is not already provided. example: US zip: type: string description: The zip or postal code for the address given. Required only for countries that use zip/postal. example: '78701' PartialUpdateSubscription: description: Update the current retries before the subscription expires. properties: subscription: $ref: '#/components/schemas/PartialUpdateSubscriptionEntity' type: object PartialUpdateSubscriptionEntity: allOf: - type: object properties: current_retries: type: integer example: 6 - $ref: '#/components/schemas/SubscriptionNotesEntity' - $ref: '#/components/schemas/SubscriptionOrderCountEntity' UpdateSubscriptionLineItems: description: Update line items on the subscription. type: object title: '' properties: subscription: type: object properties: line_items: type: array items: $ref: '#/components/schemas/PatchLineItemEntity' CreateSubscriptionLineItems: description: Add line items to a subscription. type: object required: - platform_product_id - platform_variant_id - quantity properties: line_items: type: array items: properties: platform_product_id: type: string description: The ID of the product on your platform. Learn more about [finding platform product IDs](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-platform_product_id-and-platform_variant_id-for-a-line-item). example: '1357908642' platform_variant_id: type: string description: 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](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-platform_product_id-and-platform_variant_id-for-a-line-item). example: '2468097531' quantity: type: integer description: The quantity of this line item within the subscription. example: 1 price: type: integer description: 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. example: 3500 subscription_group_id: type: integer description: 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](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-subscription_group_id-for-a-line-item). example: 123 UpdateSubscriptionNextOrderDate: description: Update the next order date and time for the subscription. type: object properties: nextDate: type: string example: '2020-01-20T18:00:00Z' includeFutureOrders: type: boolean default: false description: Also adjust the order datetimes of all future orders to match the new next order date with the old interval. SkipSubscriptionOrder: description: Skip an upcoming order for the subscription. properties: date: type: string example: '2020-01-20T18:00:00Z' type: object UnskipSubscriptionOrder: description: Restore a previously skipped future subscription order. properties: date: type: string description: The date of the previously skipped order (to be restored/unskipped) example: '2020-01-20T18:00:00Z' type: object SelectionOptions: properties: selection_options: type: array items: $ref: '#/components/schemas/SelectionOptionsEntity' pagination: $ref: '#/components/schemas/SubscriptionsCursorPagination' type: object SelectionOptionsEntity: type: object title: '' properties: id: type: integer example: 1 description: Selection Options identifier. readOnly: true shop_id: type: integer example: 10 readOnly: true description: The shop ID. subscription_group_id: type: integer example: 9 readOnly: true description: The subscription group the selection option belong to. platform_entity_id: type: integer example: 8000319815956 readOnly: true description: The platform identifier to the product in the selection option. bold_platform_entity_id: type: integer example: 39 readOnly: true description: The Bold identifier of the product in the selection option. created_at: type: string example: '2022-11-09 17:50:37' description: When the selection option was created. updated_at: type: string example: '2022-11-09 17:50:37' description: When the selection option was updated. deleted_at: type: string nullable: true example: null description: When the selection option was deleted. required: - id - shop_id - subscription_group_id - platform_entity_id - bold_platform_entity_id - created_at - updated_at - deleted_at SubscriptionGroups: properties: subscription_groups: type: array items: $ref: '#/components/schemas/SubscriptionGroupEntity' type: object SubscriptionGroup: properties: subscription_group: $ref: '#/components/schemas/SubscriptionGroupEntity' type: object SubscriptionGroupEntity: type: object title: '' properties: id: type: integer example: 19364 readOnly: true shop_id: type: integer example: 8846 readOnly: true internal_name: type: string example: Standard Subscription is_enabled: type: boolean example: true platform_id: type: string example: gid://shopify/SellingPlanGroup/132016692 allow_prepaid: type: boolean example: false is_prepaid_only: type: boolean example: false should_continue_prepaid: type: boolean example: false continue_prepaid_type: type: string example: as_prepaid enum: - as_prepaid - as_standard allow_buffer_days: type: boolean discount_type: type: string example: no_discount enum: - no_discount - percentage - fixed percent_discount: type: number example: 11 fixed_discount: type: integer minimum_order_count_before_cancellable: type: integer example: 0 is_product_swappable: type: boolean example: false is_subscription_only: type: boolean example: false selection_type: type: string example: products enum: - products - collections group_type: type: string example: selectable enum: - selectable - fixed selectable_daily_allowed: type: boolean example: false selectable_weekly_allowed: type: boolean example: false selectable_yearly_allowed: type: boolean example: false selectable_max_interval_frequency: type: integer example: 0 fixed_interval_type: type: string example: monthly enum: - daily - weekly - monthly - yearly is_fixed_billing: type: boolean example: false can_add_to_cart: type: boolean example: true created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true deleted_at: type: string example: null format: date-time nullable: true readOnly: true active_subscribers_count: type: integer example: 1 readOnly: true billing_rules: type: array items: $ref: '#/components/schemas/BillingRuleEntity' selection_options: type: array items: $ref: '#/components/schemas/SelectionOptionEntity' prepaid_durations: type: array items: $ref: '#/components/schemas/PrepaidDuration' dynamic_discounts: type: array nullable: true description: | 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 items: $ref: '#/components/schemas/DynamicDiscount' required: - id - shop_id - internal_name - is_enabled - platform_id - allow_prepaid - is_prepaid_only - should_continue_prepaid - continue_prepaid_type - allow_buffer_days - discount_type - percent_discount - fixed_discount - minimum_order_count_before_cancellable - is_product_swappable - is_subscription_only - selection_type - group_type - selectable_daily_allowed - selectable_weekly_allowed - selectable_yearly_allowed - selectable_max_interval_frequency - fixed_interval_type - is_fixed_billing - can_add_to_cart - created_at - updated_at - deleted_at - active_subscribers_count - billing_rules - selection_options - prepaid_durations SubscriptionOrders: properties: subscription_orders: type: array items: $ref: '#/components/schemas/SubscriptionOrderEntity' type: object SubscriptionOrder: type: object properties: id: type: integer example: 1008130 subscription_id: type: integer example: 316561 shop_id: type: integer example: 6481 base_to_charged_exchange_rate: type: number example: 1 base_currency: type: string example: CAD order: $ref: '#/components/schemas/OrderEntity' is_multi_currency: type: boolean created_at: type: string example: '2021-07-09T18:13:40Z' updated_at: type: string example: '2021-07-09T18:13:40Z' nullable: true required: - id - subscription_id - shop_id - base_to_charged_exchange_rate - base_currency - order - is_multi_currency - created_at - updated_at title: '' SubscriptionOrderEntity: properties: id: type: integer example: 151917 subscription_id: type: integer example: 5266 shop_id: type: integer example: 29875 currency: type: string example: CAD base_to_charged_exchange_rate: type: integer example: 1 base_currency: type: string example: CAD order: $ref: '#/components/schemas/OrderEntity' is_multi_currency: type: boolean example: false created_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time updated_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time type: object readOnly: true SubscriptionAdjustments: properties: adjustments: type: array items: $ref: '#/components/schemas/SubscriptionAdjustment' SubscriptionAdjustment: properties: id: type: integer readOnly: true example: 74928 name: type: string description: The name of the adjustment. example: One-time Upsell (Gift) description: type: string description: The description of the adjustment being made to the subscription or its orders. example: Enjoy a complementary gift every 5th order for being a loyal customer! target: type: string description: The target of the adjustment. enum: - subscription - order example: order trigger: type: object description: The condition for when and how often the `action` will be made against the `target`. oneOf: - $ref: '#/components/schemas/SubscriptionAdjustmentTriggerOrderCount' - $ref: '#/components/schemas/SubscriptionAdjustmentTriggerOrderDatetime' action: type: object description: The action that should be made against the `target` of the adjustment. oneOf: - $ref: '#/components/schemas/SubscriptionAdjustmentActionAddLineItem' - $ref: '#/components/schemas/SubscriptionAdjustmentActionUpdateLineItemQuantity' - $ref: '#/components/schemas/SubscriptionAdjustmentActionApplyPrice' invalid_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this adjustment will be applied and become invalid. The value is null for adjustments that are scheduled to be applied one-time in the future. nullable: true readOnly: true example: null created_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this adjustment was created. readOnly: true example: '2024-10-15T06:00:00Z' updated_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this adjustment was last updated. The value is the same as the `created_at` value if the adjustment has never been updated. readOnly: true example: '2024-10-15T06:00:00Z' deleted_at: type: string format: date-time description: The date (in [RFC3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this adjustment was deleted. The value is null if the adjustment has never been deleted. nullable: true readOnly: true example: null SubscriptionAdjustmentTriggerOrderCount: required: - type properties: type: type: string description: The type of trigger to use to determine when this adjustment should apply. The value `order_count` is used to match targets based on order count. enum: - order_count example: order_count count: $ref: '#/components/schemas/SubscriptionAdjustmentMatchConditionCount' relative_count: $ref: '#/components/schemas/SubscriptionAdjustmentMatchConditionRelativeCount' function: $ref: '#/components/schemas/SubscriptionAdjustmentMatchConditionFunction' SubscriptionAdjustmentMatchConditionCount: type: integer nullable: true description: The order count of the target that the adjustment will apply to. example: 5 SubscriptionAdjustmentMatchConditionRelativeCount: type: integer description: Use the subscription's current order count when calculating the final order count. minimum: 1 example: 5 SubscriptionAdjustmentMatchConditionFunction: type: object nullable: true description: Use a "y = mx + b" formula as your match condition for when to apply your adjustment to orders. For example, a "step_size" of 3 and an "offset" of 2 to represent "Every 3rd order starting on the 2nd order." properties: step_size: type: integer minimum: 1 example: 5 offset: minimum: 0 type: integer example: 0 SubscriptionAdjustmentTriggerOrderDatetime: required: - type properties: type: type: string description: The type of trigger to use to determine when this adjustment should apply. The value `order_datetime` is used to match targets based on order date and time. enum: - order_datetime example: order_datetime datetime: type: string format: date-time description: The date and time of an order that will trigger this adjustment. example: '2024-02-15T06:00:00Z' SubscriptionAdjustmentActionAddLineItem: required: - type - platform_product_id - platform_variant_id - quantity properties: type: type: string description: |- The action to perform for the adjustment. Adds a line item to the adjustment target. To add a line item, the `type` value is always "add_line_item". enum: - add_line_item example: add_line_item platform_product_id: type: string description: The ID of the product on your platform. Learn more about [finding platform product IDs](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-platform_product_id-and-platform_variant_id-for-a-line-item). example: '1578934692' platform_variant_id: type: string description: 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](/guides/subscriptions-v2/create-subscription#how-do-i-find-the-platform_product_id-and-platform_variant_id-for-a-line-item). example: '975285185' quantity: type: integer description: The quantity of the line item to add. example: 1 price: type: integer description: The price of the line item in the base currency unit (e.g. cents). example: 1500 SubscriptionAdjustmentActionUpdateLineItemQuantity: required: - type - subscription_line_item_id - quantity properties: type: type: string description: |- The action to perform for the adjustment. Updates a line item quantity for the adjustment target. To update a line item's quantity, the `type` value is always "update_line_item_quantity". enum: - update_line_item_quantity example: update_line_item_quantity subscription_line_item_id: type: number description: The ID of the subscription line item to update. example: 35236 quantity: type: integer description: The new quantity of the line item. example: 3 SubscriptionAdjustmentActionApplyPrice: required: - type - line_item_id - price properties: type: type: string description: |- The action to perform for the adjustment. It updates the price for the adjustment target. To update a line item's price, the `type` value is always "apply_price". enum: - apply_price example: apply_price line_item_id: type: number description: The ID of the subscription line item to update. example: 35237 price: type: integer description: The new price of the line item in the base currency unit (e.g. cents). example: 300 SwapProduct: type: object properties: swap_products: type: array items: $ref: '#/components/schemas/SwapProductEntity' SwapProductEntity: type: object properties: line_item_id: type: integer example: 1 platform_product_id: type: string example: '1357908642' platform_variant_id: type: string example: '2468097531' subscription_group_id: type: integer example: 1 SwappableProducts: properties: swappable_products: type: array items: $ref: '#/components/schemas/SwappableProductEntity' pagination: $ref: '#/components/schemas/StandardPaginationEntity' type: object SwappableProductEntity: type: object readOnly: true properties: price: type: integer readOnly: true example: 1337 price_charged: type: integer readOnly: true example: 1337 discounted_price: type: integer readOnly: true example: 1337 discounted_price_charged: type: integer readOnly: true example: 1337 has_discount: type: boolean readOnly: true example: true url: type: string readOnly: true example: https://example-store.example.com/monthly-expansion-pack variants: type: array readOnly: true items: $ref: '#/components/schemas/SwappableProductVariantEntity' image: type: string readOnly: true example: https://example.com/s-sadjid0asd/products/112/images/376/example-store__33773.1574282899.386.513.png?c=1 product_image: type: string readOnly: true example: https://example.com/s-sadjid0asd/products/112/images/376/example-store__33773.1574282899.386.513.png?c=1 title: type: string readOnly: true example: Monthly Expansion Pack product_name: type: string readOnly: true example: Monthly Expansion Pack platform_product_id: type: string readOnly: true example: '1357908642' subscription_group_id: type: integer readOnly: true example: 1 ConvertibleAdjustmentGroup: type: object required: - on_cycle_end - trigger properties: id: type: integer example: 1 readOnly: true shop_platform_id: type: integer example: 1234 readOnly: true on_cycle_end: type: string enum: - repeat_cycle - continue_last_item - remove_from_subscription example: repeat_cycle trigger: type: object required: - type - count properties: type: type: string example: order_count function: type: object nullable: true readOnly: true example: null count: type: integer example: 1 created_at: type: string readOnly: true example: '2024-03-11T18:56:12Z' format: date-time updated_at: type: string readOnly: true example: '2024-03-11T18:56:12Z' format: date-time deleted_at: type: string example: null readOnly: true format: date-time nullable: true ConvertibleAdjustmentGroupItemEntity: required: - type - discount_type type: object properties: type: type: string enum: - product - initial_product example: product product: $ref: '#/components/schemas/ConvertibleAdjustmentGroupItemProduct' discount_value: type: integer example: 50 discount_type: type: string enum: - percentage - fixed - no_discount example: percentage ConvertibleAdjustmentGroupItem: type: object properties: id: type: integer description: The convertible adjustment item identifier. example: 81 shop_platform_app_id: type: integer description: The identifier of the application. example: 1007 convertible_adjustment_group_id: type: integer description: The convertible adjustment group identifier, obtained from calling [Create Convertible Adjustment Group](/api/subscriptions#tag/Convertible-Adjustments/operation/CreateConvertibleAdjustmentGroup). example: 20 type: type: string description: The type of convertible adjustment group item. enum: - product example: product discount_value: type: integer description: The value given to the discount. For fixed discounts, cents off (e.g. 500 for $5) should be provided. For percent discounts, the percentage off (e.g. 10) should be provided. example: 50 discount_type: type: string description: The type of discount applied to the recurring product enum: - percentage - fixed - no_discount example: percentage product: type: object description: The product involved in the convertible adjustment. properties: id: type: integer description: The product identifier. example: 81 convertible_adjustment_group_item_id: type: integer description: The convertible adjustment group item identifier. example: 81 platform_product_id: type: string description: The identifier of the product on the platform. example: '7873884881051' platform_variant_id: type: string description: The identifier of the variant on the platform. example: '44147854114971' product_id: type: string description: The identifier of the product nullable: true example: '11' variant_id: type: string description: The identifier of the variant nullable: true example: '22' created_at: type: string description: The date and time the product was created. format: date-time example: '2024-03-19T20:42:47Z' updated_at: type: string description: The date and time the product was updated. format: date-time example: '2024-03-19T20:42:47Z' deleted_at: type: string description: The date and time the product was deleted. format: date-time nullable: true example: null created_at: type: string description: The date and time the convertible adjustment group item was created. format: date-time example: '2024-03-19T20:42:47Z' updated_at: type: string description: The date and time the convertible adjustment group item was updated. format: date-time example: '2024-03-19T20:42:47Z' deleted_at: type: string description: The date and time the convertible adjustment group item was deleted. format: date-time nullable: true example: null ConvertibleAdjustmentGroupItemProduct: type: object nullable: true required: - platform_product_id - platform_variant_id properties: platform_product_id: type: string description: The identifier of the product on the platform. example: '7873884881051' platform_variant_id: type: string description: The identifier of the variant on the platform. example: '44147854114971' WebhookTopicEntity: type: object properties: id: type: integer topic_name: type: string x-examples: subscription_created: id: 1 topic_name: subscription_created subscription_updated: id: 2 topic_name: subscription_updated WebhookEventEntity: title: '' type: object properties: id: type: integer shop_id: type: integer webhook_subscription_id: type: integer webhook_topic_id: type: integer uuid: type: string attempts: type: integer last_response_status_code: type: string delivered_at: type: string created_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time updated_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time deleted_at: type: string example: null readOnly: true format: date-time nullable: true x-examples: Example: id: 1 shop_id: 1 webhook_subscription_id: 1 webhook_topic_id: 1 uuid: 18418f32-f1ff-4897-94c9-9daacbaa404b attempts: 1 last_response_status_code: '200' delivered_at: '2020-08-17T18:27:03Z' created_at: '2020-08-17T18:27:03Z' updated_at: '2020-08-17T18:27:03Z' deleted_at: '' description: '' WebhookSubscriptionEntity: type: object x-examples: Example: id: 1 shop_id: 1 webhook_topic_id: 1 callback_url: yourapp.com/bold-subscription-creation-callback created_at: '2020-08-13T15:39:01Z' updated_at: '2020-08-13T15:39:01Z' deleted_at: '' properties: id: type: integer shop_id: type: integer webhook_topic_id: type: integer callback_url: type: string shared_secret: type: string created_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time updated_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time deleted_at: type: string example: null readOnly: true format: date-time nullable: true WebhookTopics: properties: webhook_topics: type: array items: $ref: '#/components/schemas/WebhookTopicEntity' type: object WebhookSubscription: title: '' type: object properties: webhook_subscription: $ref: '#/components/schemas/WebhookSubscriptionEntity' WebhookSubscriptions: title: '' type: object properties: webhook_subscriptions: type: array items: $ref: '#/components/schemas/WebhookSubscriptionEntity' WebhookEvents: properties: webhook_events: type: array items: $ref: '#/components/schemas/WebhookEventEntity' type: object description: '' x-examples: {} WebhookEvent: type: object properties: webhook_event: $ref: '#/components/schemas/WebhookEventEntity' SwappableProductVariantEntity: type: object readOnly: true x-examples: {} properties: platform_id: type: string example: '1' platform_product_id: type: string example: '112' name: type: string example: Size Small sku: type: string example: SKU-112-Small price: type: integer example: 1337 price_charged: type: integer example: 1337 discounted_price: type: integer example: 1337 discounted_price_charged: type: integer example: 1337 discounted_cost: type: integer example: 1337 discounted_cost_charged: type: integer example: 1337 cost: type: integer example: 0 weight: type: number example: 1.5 weight_unit: type: string example: kg grams: type: integer example: 1500 image_id: type: integer example: 0 image_url: type: string example: '' allow_backorder: type: boolean example: false inventory_quantity: type: integer example: 0 inventory_tracking_service: type: string example: platform inventory_tracking_entity: type: string example: product title: '' AlternatePaymentMethod: description: '' type: object properties: gift_card: type: array uniqueItems: true minItems: 1 items: required: - payment_public_id - card_number - balance properties: payment_public_id: type: string minLength: 1 card_number: type: string minLength: 1 balance: type: number required: - gift_card x-examples: example-1: gift_card: - payment_public_id: Z44qfpucJ1dsQjuZopMpFuQNyKCv7Eui0JLCHq9y1ytE669TlqGChkrl92xxhTXy card_number: SADWIUWRFNRVDTCB balance: 1200 PrepaidDuration: title: PrepaidDuration type: object properties: id: type: integer readOnly: true total_duration: type: integer minimum: 1 discount_value: type: integer discount_type: type: string enum: - percentage - fixed - no_discount created_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time updated_at: type: string readOnly: true example: '2019-11-20T20:31:55Z' format: date-time deleted_at: type: string example: null readOnly: true format: date-time nullable: true DynamicDiscount: title: DynamicDiscount type: object description: | Dynamic Discount is applied when the provided number of orders are placed. The fixed discount value is in the base currency unit (e.g. cents). Example: Base product price: $10.00 Discount: {"order_number": 2, "discount_type": "fixed", "discount_value": 250} The $2.50 discount will be applied after the second order, and the line item price will be changed to $7.50. properties: order_number: type: integer minimum: 1 discount_type: type: string example: fixed enum: - percentage - fixed discount_value: type: number minimum: 0 example: 25 SubscriptionAndPaymentMethod: title: SubscriptionAndPaymentMethod type: object properties: payment_method: $ref: '#/components/schemas/PaymentMethodEntity' subscription: $ref: '#/components/schemas/SubscriptionEntity' x-examples: Example: value: payment_method: public_id: jik1w6HrCn17CxXPDkWhtgyqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG cc_type: Visa expiration: date: 2020-05 timezone_type: 'null' timezone: 'null' last_four: '1111' is_default: true subscription: id: 1 shop_id: 1 next_order_datetime: '2020-01-20T18:00:00Z' next_payment_datetime: '2020-01-20T18:00:00Z' subscription_status: active payment_method_token: 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: - id: 1 subscription_id: 1 bold_platform_subscription_id: 1 bold_platform_subscription_line_item_id: 1 platform_product_id: '1357908642' platform_variant_id: '2468097531' subscription_group_id: 1 subscription_group_billing_rules_id: 1 product_name: Monthly Expansion Pack variant_name: Default Title title: Monthly Expansion Pack sku: SKU-113-Red url: https://example-store.example.com/monthly-expansion-pack image: '' quantity: 1 price: 3500 price_charged: 3500 discounted_price: 3200 discounted_price_charged: 3200 full_price: 3200 full_price_charged: 3200 requires_shipping: false grams: 2200 weight: 2.2 weight_unit: kg taxable: true discounts: - id: 1 subscription_line_item_id: 1 shop_id: 5 discount_type: percentage percentage_value: 10 fixed_value: 0 description: Subscription discount (10%) for Monthly Expansion Pack created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' placed_at: '2012-01-20T18:00:00Z' created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' customer: id: 0 platform_id: 0 cashier_public_id: string first_name: John last_name: Doe phone: 800-555-0102 email: john.doe@example.com notes: Loyal customer. addresses: - id: 0 shop_identifier: string platform_id: 0 customer_id: 0 platform_type: string platform_customer_id: 123456789 first_name: John last_name: Doe company: Example Company phone: 800-555-0102 street1: 123 example st. street2: '101' city: Toronto province: Ontario province_code: 'ON' country: Canada country_code: CA zip: M5V 3L9 is_default: true created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' default_address: id: 0 shop_identifier: string platform_id: 0 customer_id: 0 platform_type: string platform_customer_id: 123456789 first_name: John last_name: Doe company: Example Company phone: 800-555-0102 street1: 123 example st. street2: '101' city: Toronto province: Ontario province_code: 'ON' country: Canada country_code: CA zip: M5V 3L9 is_default: true created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' subscription_summary: customer_id: 0 next_order_date: '2020-01-20T18:00:00Z' last_order_date: '2019-11-20T20:55:27Z' active_subscription_count: 2 inactive_subscription_count: 0 subscription_order_count: 5 labels: - id: 0 customer_id: 0 name: bsub_subscription_active created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' deleted_at: null shipping_lines: - id: 0 name: Standard Shipping code: Standard Shipping price: 1000 value: 1000 tag: Shipping created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' subscription_id: 1 billing_address: id: 0 shop_identifier: string platform_id: 0 customer_id: 0 platform_type: string platform_customer_id: 123456789 first_name: John last_name: Doe company: Example Company phone: 800-555-0102 street1: 123 example st. street2: '101' city: Toronto province: Ontario province_code: 'ON' country: Canada country_code: CA zip: M5V 3L9 is_default: true created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' deleted_at: '2019-11-20T20:31:55Z' shipping_address: id: 0 shop_identifier: string platform_id: 0 customer_id: 0 platform_type: string platform_customer_id: 123456789 first_name: John last_name: Doe company: Example Company phone: 800-555-0102 street1: 123 example st. street2: '101' city: Toronto province: Ontario province_code: 'ON' country: Canada country_code: CA zip: M5V 3L9 is_default: true created_at: '2019-11-20T20:31:55Z' updated_at: '2019-11-20T20:31:55Z' deleted_at: '2019-11-20T20:31:55Z' idempotency_key: JwGdN55C4g1z5FXRO8Hp21CMxUxKyo6VcGSf3cUsjCgNyTtoeZcIsGM1We4p7pCe-0 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 note: Staff note order_note: Customer note SubscriptionOrderTransactionFailed: title: SubscriptionOrderTransactionFailed type: object properties: id: type: integer example: 123 bold_platform_subscription_id: type: integer example: 234 shop_platform_app_id: type: integer example: 345 failure_reason: type: string example: cashier cashier_response: type: string example: '{"success":false,"errors":{"code":"order_creation_failed","message":"","service":"cashier","service_type":"cashier"}}' current_retries: type: integer example: 3 max_retries: type: integer example: 3 created_at: type: string format: date-time example: '2019-11-20T20:31:55Z' customer: $ref: '#/components/schemas/CustomerEntity' required: - id - bold_platform_subscription_id - shop_platform_app_id - failure_reason - cashier_response - current_retries - max_retries - created_at - shop_identifier SubscriptionUpdateLineItemsEntity: allOf: - type: object x-examples: {} properties: id: type: integer example: 1 readOnly: true external_id: type: string nullable: true customer: example: 'null' shop_id: type: integer example: 1 readOnly: true next_order_datetime: type: string example: '2020-01-20T18:00:00Z' next_payment_datetime: type: string example: '2020-01-20T18:00:00Z' next_processing_datetime: type: string example: '2020-01-20T18:00:00Z' subscription_status: type: string enum: - active - inactive - paused - scheduled - processing - app_uninstalled - waiting_sca_authorization example: active status_changed_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true sca_url: type: string example: https://bank.com/pCkWhtgQQVM8W/sca nullable: true readOnly: true payment_method_token: type: string example: jik1w6HrCn17CxXPcKwHTGqqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG payment_gateway_public_id: type: string example: jik1w6HrCn17CxXPcKwHTGqqvm8wLDd1PelY6k8mabglNmL8XKBnsde9PdgKZqnG nullable: true payment_rrule: type: string example: DTSTART:20200120T180000Z\nRRULE:FREQ=MONTHLY\nEXDATE:20200220T180000Z payment_rrule_text: type: string example: Monthly nullable: true order_rrule: type: string example: DTSTART:20200120T180000Z\nRRULE:FREQ=MONTHLY\nEXDATE:20200220T180000Z order_rrule_text: type: string example: Monthly nullable: true last_payment_datetime: type: string example: '2019-11-20T20:55:26Z' nullable: true last_order_datetime: type: string example: '2019-11-20T20:55:26Z' nullable: true last_processed_datetime: type: string example: '2019-11-20T20:55:26Z' nullable: true current_retries: type: integer example: 3 charged_currency: type: string example: CAD base_to_charged_exchange_rate: type: integer example: 1 base_currency: type: string example: CAD line_items: type: array items: $ref: '#/components/schemas/UpdateLineItemEntity' readOnly: true shipping_lines: type: array items: $ref: '#/components/schemas/ShippingLineEntity' readOnly: true billing_address: $ref: '#/components/schemas/CustomerAddressEntity' shipping_address: $ref: '#/components/schemas/CustomerAddressEntity' idempotency_key: type: string example: JwGdN55C4g1z5FXRO8Hp21CMxUxKyo6VcGSf3cUsjCgNyTtoeZcIsGM1We4p7pCe-0 placed_at: type: string example: '2012-11-20T20:31:55Z' format: data-time nullable: true created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true percent_discount: type: number example: 10 nullable: true readOnly: true discount_code: type: string example: DISCOUNTCODE readOnly: true customer_id: type: integer example: 1697912 readOnly: true billing_address_id: type: integer example: 11697812 shipping_address_id: type: integer example: 11697812 orders_processed: type: integer example: 1 nullable: true last_failure_code: type: string example: card_expired description: This code may help to identify the type of the error. nullable: true 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 - 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 last_failure_details: type: object nullable: true description: Default error messages for the last_failure_code field required: - message properties: message: type: string description: Error message example: The order couldn't process because the card was declined. nullable: false last_failure_reason: type: string example: credit_card description: The reason for the failure nullable: true enum: - credit_card - gateway - cashier - platform - inventory - other - $ref: '#/components/schemas/SubscriptionNotesEntity' required: - id - external_id - customer - shop_id - next_order_datetime - next_payment_datetime - next_processing_datetime - subscription_status - status_changed_at - payment_method_token - payment_gateway_public_id - payment_rrule - payment_rrule_text - order_rrule - order_rrule_text - last_payment_datetime - last_order_datetime - last_processed_datetime - current_retries - charged_currency - base_to_charged_exchange_rate - base_currency - idempotency_key - created_at - updated_at - percent_discount - customer_id - billing_address_id - shipping_address_id - note - order_note CursorPagination: type: object title: CursorPagination description: Pagination result for cursor-based paginated endpoints. properties: total: type: integer example: 15 readOnly: true count: type: integer example: 10 readOnly: true per_page: type: integer example: 10 readOnly: true total_pages: type: integer example: 2 readOnly: true next: type: string example: P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj readOnly: true nullable: true readOnly: true FutureOrdersCursorPagination: type: object title: FutureOrdersCursorPagination description: Cursor-based pagination result for future orders endpoints. properties: count: type: integer description: The count of items on the current response. example: 10 next: type: string nullable: true description: A base-64 encoded cursor that can be used on subsequent requests to get the next page. The value is `null` when no pages remain. example: P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj readOnly: true SubscriptionsCursorPagination: type: object title: CursorPagination description: Pagination result for cursor-based paginated endpoints. properties: next: type: string example: P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj readOnly: true prev: type: string example: P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj readOnly: true readOnly: true PatchLineItemEntity: type: object title: '' description: The line item to be updated. Fields marked as **read-only** cannot be updated using this endpoint. Use the property's existing value for those fields. properties: id: type: integer example: 1 nullable: true description: |- **Read-only.** Line item identifier. subscription_id: type: integer example: 1 nullable: true description: |- **Read-only.** Subscription identifier. platform_id: type: string example: ABC123 description: |- **Read-only.** Identifier from the platform. platform_product_id: type: string example: '1357908642' nullable: true description: |- **Read-only.** Product identifier from the platform. platform_variant_id: type: string example: '2468097531' nullable: true description: |- **Read-only.** Variant identifier from the platform. subscription_group_id: type: integer example: 1 description: Subscription group identifier. subscription_group_billing_rules_id: type: integer example: 1 nullable: true description: Billing rules identifier for the subscription group. title: type: string example: Monthly Expansion Pack description: Line item title. product_name: type: string example: Monthly Expansion Pack nullable: true description: |- **Read-only.** Product name. variant_name: type: string example: Default Title nullable: true description: |- **Read-only.** Variant name. sku: type: string example: SKU-113-Red description: Product SKU. url: type: string example: https://example-store.example.com/monthly-expansion-pack description: |- **Read-only.** Product URL. image: type: string example: '' description: Product image. quantity: type: integer example: 1 description: Product quantity. price: type: integer example: 3500 nullable: true description: 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: type: integer example: 3200 nullable: true description: |- **Read-only.** Influenced by changes made to the `price` field. discounted_price: type: integer example: 3200 description: |- **Read-only.** Influenced by changes made to the `price` field. discounted_price_charged: type: integer example: 3200 description: |- **Read-only.** Influenced by changes made to the `price` field. full_price: type: integer example: 3200 description: |- **Read-only.** Influenced by changes made to the `price` field. full_price_charged: type: integer example: 3200 description: |- **Read-only.** Influenced by changes made to the `price` field. requires_shipping: type: boolean example: false description: Whether or not the line item requires shipping. grams: type: integer example: 2200 description: Product weight in grams. weight: type: number example: 2.2 description: Product weight in `weight_unit`. weight_unit: type: string example: kg description: Unit used for `weight`. taxable: type: boolean example: true description: Whether or not the line item is taxable. discounts: type: array items: $ref: '#/components/schemas/LineItemDiscountEntity' description: |- **Read-only.** All discounts associated with the line item. prepaid_metadata: type: object description: |- **Read-only.** Prepaid properties, as defined in the [Create Line Item Prepaid Metadata](/api/subscriptions#tag/Subscription-Line-Items/operation/CreateLineItemPrepaidMetadata) and [Update Line Item Prepaid Metadata](/api/subscriptions#tag/Subscription-Line-Items/operation/UpdateLineItemPrepaidMetadata) endpoint. Set to `null` when using the [Update Subscription Line Items](/api/subscriptions#tag/Subscription-Line-Items/operation/UpdateLineItems) endpoint. nullable: true enum: - null example: null line_item_attributes: type: array items: $ref: '#/components/schemas/LineItemAttributeEntity' description: |- **Read-only.** Additional attributes associated with the line item. Use the [Update Line Item Attributes](subscriptions#operation/UpdateLineItemAttributes) endpoint to add, update, or delete line item attributes. created_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true updated_at: type: string example: '2019-11-20T20:31:55Z' format: date-time readOnly: true required: - id - subscription_id - platform_id - platform_product_id - platform_variant_id - subscription_group_id - subscription_group_billing_rules_id - title - product_name - variant_name - sku - url - image - quantity - price_charged - discounted_price - discounted_price_charged - full_price - requires_shipping - grams - weight - weight_unit - taxable - discounts - prepaid_metadata readOnly: true createdAt: type: string description: The date and time when the object was created. example: '2022-12-25T00:00:00Z' format: date-time readOnly: true updatedAt: type: string description: The date and time when the object was most recently updated. example: '2022-12-25T00:00:00Z' format: date-time readOnly: true nullable: true deletedAt: type: string description: The date and time when the object was deleted. Set to `null` when the object was not deleted. example: '2022-12-25T00:00:00Z' format: date-time nullable: true parameters: shop_identifier_path_param: name: shop_identifier in: path description: The unique identifier of the shop. required: true schema: type: string example: '123456' customer_id_path_param: name: customer_id in: path description: The customer identifier. required: true schema: type: integer example: 12 address_id_path_param: name: address_id in: path description: The address identifier. required: true schema: type: integer subscription_id_path_param: name: subscription_id in: path description: The subscription identifier. required: true schema: type: integer subscription_adjustment_id_path_param: name: adjustment_id in: path description: The subscription adjustment identifier. required: true schema: type: integer convertible_adjustment_group_id_path_param: name: adjustment_id in: path description: The convertible adjustment group identifier, obtained from calling [Create Convertible Adjustment Group](/api/subscriptions#tag/Convertible-Adjustments/operation/CreateConvertibleAdjustmentGroup). required: true schema: type: integer convertible_adjustment_group_item_id_path_param: name: adjustment_item_id in: path description: The convertible adjustment group item identifier, obtained from calling [Create Convertible Adjustment Group Items](/api/subscriptions#tag/Convertible-Adjustments/operation/CreateConvertibleAdjustmentGroupItems). required: true schema: type: integer filter_subscription_adjustments_query_param: schema: type: string in: query name: filter description: 'Accepts filtering options as described in [Query & Pagination](/guides/getting-started/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)`' order_id_path_param: name: order_id in: path description: The order identifier. required: true schema: type: integer subscription_interval_id_path_param: name: subscription_interval_id in: path description: The subscription interval identifier. required: true schema: type: integer line_item_id_path_param: name: line_item_id in: path description: Line item ID to view and manage data for. required: true schema: type: integer group_id_path_param: name: group_id in: path description: The subscription group identifier. required: true schema: type: integer webhook_subscription_id_path_param: name: webhook_subscription_id in: path description: The webhook subscription identifier. required: true schema: type: integer webhook_event_id_path_param: name: webhook_event_id in: path description: The webhook event identifier. required: true schema: type: integer limit: name: limit in: query required: false description: The maximum number of results to be returned. schema: type: integer example: 10 default: 50 page: name: page in: query required: false description: The page to request. schema: type: integer default: 1 example: 2 cursor: name: cursor in: query required: false description: 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. schema: type: string example: P3NpbmNlX2lkPTE1Mjc0Jm9yZGVyX2J5PWlkJm9yZGVyX2RpcmVjdGlvbj1kZXNj filter_future_orders_query_param: schema: type: string example: lte(order_datetime:2024-05-10T23:59:59) in: query name: filter description: Filter future orders. Accepts filtering options as described in the [Query and Pagination](/guides/subscriptions-v2/resources/query-pagination) reference. filter_future_order_subscriptions_query_param: schema: type: string example: eq(bold_customer_id:3623267) in: query name: subscription_filter description: |- Filter future orders. Accepts filtering options as described in the [Query and Pagination](/guides/subscriptions-v2/resources/query-pagination) reference. To see available filters, refer to the [Future Orders](/guides/subscriptions-v2/view-future-orders) guide. customerStatus: name: status in: query required: false description: Customer status to filter. schema: type: string enum: - all - active - inactive default: all example: active customerSearch: name: search in: query required: false description: Search with a specific target. It's possible to search by subscription ID or phone number. schema: type: string examples: bySubscription: summary: By subscription ID value: '#1234' byPhone: summary: By phone value: '123456' event_actor_type_header: in: header name: Event-Actor-Type required: true description: The type of actor that triggered the webhook event. schema: type: string enum: - store_admin - customer - integration - subscription_app shop_identifier_header: in: header name: Shop-Identifier required: true description: The unique identifier of the shop. schema: type: string enum: - '{$request.path.shop_identifier}' latest: in: query name: latest required: false description: |- 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. schema: type: boolean default: false example: true