Bold Subscriptions V1 Integrations

caution

• If you are looking for API documentation and your app version is Bold Subscriptions or Bold Subscriptions for Shopify Checkout, visit the Bold Subscriptions API Documentation. All new integrations MUST be built using these APIs.
• The documentation found on this page applies only to Bold Subscriptions V1. These APIs are only available to Bold Subscriptions V1 users on Shopify Checkout. Bold does NOT permit new integrations to be built using Bold Subscriptions V1.
• To see which version of the app you have installed, visit the Bold Subscriptions Admin. To learn more about the feature differences between Bold Subscriptions V1 and Bold Subscriptions for Shopify Checkout, refer to the Help Center.

Introduction

Bold Subscriptions customers using the Advanced plan or higher can use our third party API and webhooks integration to interact with subscription data in unique ways. This includes the ability to modify, cancel and report on subscriptions as well as get notified about various subscription-related events. Generally our API follows the business rules set in the app. If you currently have not enabled a setting to allow customers to make the change, or cannot do the action in the admin, then the majority of the time you will not be able to perform the action via the API. Contact Bold for more information on these tools and gaining access.

Using Webhooks

Event Subscriptions

To register webhooks go into the Bold Subscriptions admin under Integrations -> Webhooks. Webhooks must use a secure protocol (https) and respond with a 200 status in a reasonable amount of time.

Learn about registering webhooks in Bold Subscriptions

Receiving Webhooks

When events occur that you have subscribed to, we will deliver the webhook(s) in batches every 10 minutes. To deliver the webhook we will send a request to your webhook URL in the following format:

POST https://example.com/my_webhooks/receive HTTPS/1.1
X-Bold-Signature: e9f65715bbc9222477b27074804bbdd5c73cde62f84d8b00cfd05b883534af3d
timestamp: 1556410547
Content-Type: application/json
charset: utf-8

See the sample webhook payloads further down on this page for a preview of how the request body is formatted.

Securing Webhooks

Like APIs, webhooks can also be prone to various cyber attacks such as replay attacks and timing attacks. To protect yourself from receiving unwanted or untrusted data we recommend verifying the request we send you.

Bold Subscriptions uses an hmac sha256 hashing algorithm to add a signature to each request. In PHP, the way we build the signature would look like this:

$now = time(); // current unix timestamp
$json = json_encode($payload, JSON_FORCE_OBJECT);
$signature = hash_hmac('sha256', $now.'.'.$json, $signingKey);

Where $payload is the body of the request and $signingKey is the shared secret provided to you in the Bold Subscriptions admin.

To secure your request we recommend for you to build this same hash in your program and compare it to the signature in the request headers (X-Bold-Signature) using constant time string comparison. Another action you can take is to check that the timestamp from the headers is recent (e.g. within the last minute).

Retry Policy

In the event of a 4XX or 5XX response code from a request to your webhook URL we will attempt to deliver it again. We will retry delivering webhooks up to a maximum of 10 attempts over an increasing period of time. The formula we use to calculate the next retry time is as follows:

60 + {numberOfAttempts}^4 = Number of seconds into the future

Number of attempts	Seconds until valid retry time
1	61 seconds
2	76 seconds
3	141 seconds
4	316 seconds
.	...
9	6621 seconds (1.84 hours)

note

Although the retry time may be in the past, webhooks get delivered in batches every 10 minutes which could delay the retry up to that amount of time.

Webhook Events

When logged into the Bold Subscriptions admin you can test each of the events you're subscribed to by sending sample data to your webhook URL. You can also see below for the payloads of each event type.

Note: Some sample payloads contain the text "<event.name>" in place of the corresponding event name.

Subscription Created

A new subscription was created by a new or existing customer in the checkout.

Event Name	Triggers
subscription.created	Successful checkout

Subscription Ended

An existing subscription has been cancelled or has expired.

Event Name	Triggers
subscription.ended	Cancelled by customer Cancelled by admin Cancelled through API Prepaid or limited length subscription has expired Exceeded failed transaction limit

Subscription Cancelled

An existing subscription has been cancelled by the customer. This will not fire if a subscription has expired, been cancelled by the store owner, or cancelled via the API.

Event Name	Triggers
subscription.cancelled	Cancelled by customer

Subscription Reactivated

A subscription which was previously inactive has been reactivated by the store owner. This can only be completed via the subscriptions app.

Event Name	Triggers
subscription.activated	Reactivated by admin

Subscription Paused

A subscription was paused indefinitely.

Event Name	Triggers
subscription.paused	Paused by admin Paused by customer Paused through API

Subscription Resumed

A paused subscription was resumed.

Event Name	Triggers
subscription.resumed	Resumed by admin Resumed by customer Resumed through API

Subscription Exceptions Removed

All subscription exceptions have been removed. This includes product quantity exceptions, order skips and order shipping rate exceptions for any upcoming orders.

Event Name	Triggers
subscription.exceptions_removed	Next order date changed Subscription frequency changed Subscription ended or cancelled

Subscription Product Quantity Changed

{
	"event_type": "<event.name>",
	"event_time": "2019-03-27 11:24:51",
	"data": {
	    "products_added": [],
	    "products_removed": [],
	    "current_products": [
	        {
                "id": 1,
                "shop_app_id": 1,
                "bold_order_id": 1,
                "product_id": 1111111,
                "variant_id": 2222222,
                "converted_price": 0,
                "price": 12.00,
                "quantity": 1,
                "gram": 100,
                "product_title": "Example Product",
                "variant_title": "Small",
                "status": 0,
                "price_changed": 0,
                "shopify_price": 20.00,
                "shopify_new_price": null,
                "sku": "skuexapmple",
                "shopify_inventory": null,
                "inventory_management": "shopify",
                "taxable": 1,
                "properties": "{}",
                "vendor": "Vendor",
                "is_active": 1
	        }
	    ],
		"subscription": { ... },
		"shop": { ... }
	}
}

The quantity of a subscription product was changed. This is the global quantity for the subscription. If there are any order quantity exceptions for specific upcoming orders they will still take precedence.

Event Name	Triggers
subscription.product_quantity_changed	Changed by admin Changed by customer Changed through API

Subscription Order Date Changed

The next order date has been changed for the subscription. As a result this means all the upcoming orders have been adjusted according to the new date and frequency of the subscription.

Event Name	Triggers
subscription.order_date_changed	Changed by admin Changed by customer Changed through API

Subscription Product Added

{
	"event_type": "<event.name>",
	"event_time": "2019-03-27 11:24:51",
	"data": {
	    "products_added": [
	        {
	            "product_id": 1111111,
	            "variant_id": 2222222
	        }
	    ],
	    "products_removed": [],
	    "current_products": [
	        {
                "id": 1,
                "shop_app_id": 1,
                "bold_order_id": 1,
                "product_id": 1111111,
                "variant_id": 2222222,
                "converted_price": 0,
                "price": 12.00,
                "quantity": 1,
                "gram": 100,
                "product_title": "Example Product",
                "variant_title": "Small",
                "status": 0,
                "price_changed": 0,
                "shopify_price": 20.00,
                "shopify_new_price": null,
                "sku": "skuexapmple",
                "shopify_inventory": null,
                "inventory_management": "shopify",
                "taxable": 1,
                "properties": "{}",
                "vendor": "Vendor",
                "is_active": 1
	        }
	    ],
		"subscription": { ... },
		"shop": { ... }
	}
}

A product was added to a subscription.

Event Name	Triggers
subscription.product_added	Added by admin Added by customer

Subscription Product Removed

{
	"event_type": "<event.name>",
	"event_time": "2019-03-27 11:24:51",
	"data": {
	    "products_added": [],
	    "products_removed": [
	        {
	            "product_id": 3333333,
	            "variant_id": 5555555
	        }
	    ],
	    "current_products": [
	        {
                "id": 1,
                "shop_app_id": 1,
                "bold_order_id": 1,
                "product_id": 1111111,
                "variant_id": 2222222,
                "converted_price": 0,
                "price": 12.00,
                "quantity": 1,
                "gram": 100,
                "product_title": "Example Product",
                "variant_title": "Small",
                "status": 0,
                "price_changed": 0,
                "shopify_price": 20.00,
                "shopify_new_price": null,
                "sku": "skuexapmple",
                "shopify_inventory": null,
                "inventory_management": "shopify",
                "taxable": 1,
                "properties": "{}",
                "vendor": "Vendor",
                "is_active": 1
	        }
	    ],
		"subscription": { ... },
		"shop": { ... }
	}
}

A product was removed from a subscription.

Event Name	Triggers
subscription.product_removed	Removed by admin Removed by customer

Order Created

A new order was successfully processed. This includes a subscription's first order as well as each recurring order.

Event Name	Triggers
order.created	Successful checkout Successful recurring order

Order Failed

A new order failed to process. This is only triggered on recurring orders, and could be caused because of a failing payment method, a lack of inventory or an app misconfiguration.

Event Name	Triggers
order.failed	Recurring orders only

Order Skipped

An upcoming order was scheduled to be skipped.

Event Name	Triggers
order.skipped	Skipped by admin Skipped by customer Skipped through API

Order Resumed

An upcoming order was resumed.

Event Name	Triggers
order.resumed	Resumed by admin Resumed by customer Resumed through API

Order Quantity Exception Created

{
	"event_type": "<event.name>",
	"event_time": "2019-03-27 11:24:51",
	"data": {
		"order": {
			"date": "2019-04-15",
			"quantity": 6,
			"product_internal_id": 1357907
		},
		"subscription": { ... },
		"shop": { ... }
	}
}

The quantity of an upcoming order was changed. This does not change the global quantity of that product on the subscription, just a specific upcoming order.

Event Name	Triggers
order.quantity_exception_created	Quantity changed by admin Quantity changed by customer Quantity changed through API

Using Our API

Variables

Request Parameter variables are displayed as {parameter} with the documentation.

You can find the associated/response definitions alongside the examples in the element tables.

URL Parts

When communicating with the API your request URL should resemble the following example.

GET https://ro.boldapps.net/api/third_party/{endpoint}?shop=your-store.myshopify.com&shopify_customer_id=1234&customer_id=1234 HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

Part	Description	Required
{endpoint}	The API endpoint	Yes
shop	The permanent myshopify domain for the store as a query param	Yes
shopify_customer_id	Shopify customer ID	Yes for subscription endpoints
customer_id	Shopify customer ID	Yes for manage subscription endpoints

API Examples

We recommend viewing our sample app below containing working examples in PHP.

View PHP example app

These API reference docs are meant to clearly define the URLs, parameters, request bodies, responses and error states of the Recurring Orders Third Party API.

Authentication

The Third Party API uses a Bearer Authentication scheme. You must make a basic authentication request with your Private API Key and App Handle to receive a bearer token to use with all subsequent API requests.

The bearer token is a JWT string, generated by the server in response to a login request. The client must send this token in the BOLD-Authorization header when making requests to protected resources. This token is valid for 24 hours.

Get Token

GET api/auth/third_party_token?shop={myshopifyDomain}&handle={appHandle} HTTPS/1.1
Content-Type: application/json
BOLD-Authorization: {privateApiKey}

HTTPS/1.1 200 OK

This endpoint generates an JWT Bearer token for use with all subsequent API requests.

GET api/auth/third_party_token?shop={myshopifyDomain}&handle={appHandle}

Once you have gained access to the Third Party API, include your Private API Key in the BOLD-Authorization header to get the access token.

BOLD-Authorization: {privateApiKey}

Example response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...2ENcGARxepYj4okdGqAOwZfrm6bx4nAlQGDkq0pwDjw"
}

note

Make sure to replace {appHandle} with your application handle and {myshopifyDomain} with your full myshopify domain (e.g. example-store.myshopify.com)

Data Object

Element	Type	Description
token	string	Recurring Orders API Token

Once you have an access token, include it in the BOLD-Authorization header for every request you make:

BOLD-Authorization: Bearer {token}

The header name is BOLD-Authorization and the value of the header is Bearer {token}. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.

note

Replace {token} with your token returned from the GET /auth/third_party_token response

Manage Subscription Endpoints

GET api/third_party/manage/subscription/{endpoint}?customer_id={customer_id}&t={current_timestamp} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

Ensure you have set Content-Type: application/json header so requests do not fail. You must also include your customer ID as a GET parameter for each request.

All of our JSON responses have a standard format. The response data includes all data returned from the endpoint.

Request Parameters

Parameter	Type	In	Description	Required
customer_id	integer	query	Shopify Customer ID	true
t	timestamp	query	Current timestamp (Used to avoid Shopify caching the responses of API endpoints)	true

Example success response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "order_products": {}
  }
}

Example error response

{
  "status": 400,
  "success": false,
  "message": "Bad Request",
  "errors": {
    "message": "Unable to find a valid discount matching the code entered"
  }
}

note

All Manage Subscription endpoint responses will return a HTTP_OK (200) Response. Ensure you look at the body of the response for a status stating if it failed or not.

Response Body

Element	Description
status	The status of the HTTP response
success	Boolean value: true/false
message	Default message of the HTTP response
data	Returned data from request (only for "success": true responses)
errors	Array of errors (only for "success": false responses)

Rate Limiting

Example response headers

429 Too Many Requests HTTP/1.0
x-ratelimit-remaining: 20
x-ratelimit-limit: 20 requests per second

Example response body

{
  "message": "HTTP/1.0 429 Too Many Requests"
}

The rate limit is 20 calls per second

To ensure we maintain a stable application, Bold enforces a rate limit on the APIs outlined in this document. Bold Subscriptions V1 uses a token bucket algorithm. All requests are limited on a per-shop basis and use a single token. We encourage our users to use good system design to avoid unnecessary or duplicate calls.

All responses will include both a x-ratelimit-remaining header, indicating the amount of requests remaining; and a x-ratelimit-limit header, indicating the rate limiting policy. Requests that exceed the limit will return a 429 status code.

Other Endpoints

GET /api/third_party/subscriptions?store={myshopifyDomain}&shopify_customer_id=267534937& HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

Success response

{
    "subscriptions": [
        {
            "id": 1,
            "shopify_customer_id": 267534937,
            "interval_number": 1,
            "interval_type_id": 3,
            "first_name": "Graydon",
            "last_name": "Green",
            "customer_email": "[email protected]",
            ...
        },
        ...
    ],
}

Ensure you have set Content-Type: application/json header so requests do not fail. You must also include your Myshopify Domain as a GET parameter for each request.

All our endpoints return a JSON body type. JSON endpoints examples are contained in the json tab of the code column in the document.

Error responses will use standard HTTP headers - 400, 405, 422 etc.

Depending on the error type, a JSON response may be included with specific error information.

Discounts

Create Discount

POST api/third_party/discounts?&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
	"discount_code": "DISCOUNT1",
	"offer": {
		"type": "fixed",
		"amount": 10.00
	}
	"checkout_only": true
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "discount": {
      "id": 135,
      "type": "standard",
      "discount_code": "DISCOUNT12",
      "offer": {
        "type": "fixed",
        "amount": "10.00"
      },
      "total_uses": 0,
      "checkout_only": false,
      "discount_condition": "entire_order",
      "discount_condition_amount": "0.00",
      "orders_over_enabled": false,
      "orders_over_amount": "0.00",
      "free_shipping_amount": "0.00",
      "free_shipping_country_id": 1,
      "free_shipping_country": "All countries",
      "start_date": "0000-00-00",
      "end_date": "0000-00-00",
      "uses_per_customer": 0,
      "used": 0,
      "status": "enabled",
      "deleted": false,
      "eligible_product_list": "",
      "id_parent": 0
    }
  }
}

This endpoint can be used to create new discount codes for subscription orders.

POST api/third_party/discounts

URL Parameters

Element	Type	Description
shop	string	myshopify_url

Request Body

Element	Type	Description	Required
discount_code	string	Discount code	Yes
offer	object		Yes
type	string	The string "fixed" should be used if the discount should take a fixed dollar amount off the order. The string "percentage" should be used to take a percentage amount off the order	Yes
amount	float	The amount the discount removes from the order	Yes
total_uses	int	The total number of times a discount code can be used	No
uses_per_customer	int	The number of times a discount code can be used by a single customer	No
checkout_only	boolean	If discount is only valid on checkout (initial) orders	No
min_purchase	float	The minimum dollar purchase required to use the discount code	No
start_date	date	The date in CST, a discount becomes valid	No
end_date	date	The dates in CST, a discount becomes invalid	No

Delete Discount

DELETE api/third_party/discounts/{discount_id}?&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "Discount Code Deleted",
  "data": {
    "id": "49"
  }
}

This endpoint can be used to delete discount codes. When a discount code is deleted it will still be applied to existing subscriptions. To prevent existing subscriptions from having the discount applied also mark the discount as disabled using the disable parameter.

Delete api/third_party/discounts/{discount_id}

URL Parameters

Element	Type	Description
discount_id	integer	The id of the discount code
shop	string	myshopify_url
disable	boolean	Set to 'true' or '1' to disable

Data Object

Element	Type	Description
id	integer	Discount Code ID

Get Discounts

GET /api/third_party/discounts?shop={myshopifyDomain}&since_id={since_id}&limit={limit} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "discounts": [
      {
        "id": 135,
        "type": "standard",
        "discount_code": "DISCOUNT12",
        "offer": {
          "type": "fixed",
          "amount": "10.00"
        },
        "total_uses": 0,
        "checkout_only": false,
        "discount_condition": "entire_order",
        "discount_condition_amount": "0.00",
        "orders_over_enabled": false,
        "orders_over_amount": "0.00",
        "free_shipping_amount": "0.00",
        "free_shipping_country_id": 1,
        "free_shipping_country": "All countries",
        "start_date": "0000-00-00",
        "end_date": "0000-00-00",
        "uses_per_customer": 0,
        "used": 0,
        "status": "enabled",
        "deleted": false,
        "eligible_product_list": "",
        "id_parent": 0
      }
    ]
  }
}

This endpoint retrieves a filtered page of the store's discount codes. This endpoint is paginated, returning a page with 50 results. To retrieve the next page of results use the greatest subscription id in a subsequent request. The required URL parameters are shop, which is the store's myshopify domain.since_id which the is id of the last discount code you received. For the first page since_id should be equal to 0. As well as limit, this is the maximum number of results returned, (Note: limit cannot be set to greater than 50). To only return certain types of discount codes, use the optional URL parameters listed below.

GET /api/third_party/discounts?shop={myshopifyDomain}&since_id={since_id}&limit={limit}

URL Parameters

Element	Type	Required	Description
shop	string	yes	The store's Shopify Domain, e.g. mystore.myshopify.com
since_id	integer	yes	Subscriptions will return all discounts with id greater than the number specified. For the first page set to 0.
limit	integer	no	The page size. This can be set with any number between 1 to 50.
id	integer	no	The unique id of the discount code
type	integer	no	Refers to the discount type, standard, cancellation, bulk_group
discount_code	string	no	The string code used to identify the discount, and to be entered at checkout or on the manage subscription page
total_uses	integer	no	The total number of times a discount code can be used
checkout_only	boolean	no	Whether the discount can be used on checkout only
offer_type	integer	no	Refers to whether the discount is a fixed or percentage amount, fixed or percentage
offer_amount	string	no	The amount that the discount would subtract from the order
discount_condition	integer	no	Refers to whether the discount will remove the amount from the entire order or chosen products. (0 = entire order, 2 = these products, 3 = not these products)
discount_condition_amount	string	no	The minimum order total amount for a discount code to be applied
free_shipping_amount	string	no	If the shipping amount is less than or equal to this value and discount_type is set to 3 then free shipping is applied
free_shipping_country_id	integer	no	The ids countries that qualify for free shipping
free_shipping_country	string	no	The countries that qualify for free shipping if discount code is of type 3
start_date	date	no	The date in CST, that a discount code will become valid
end_date	date	no	The date in CST, that a discount code will become invalid
used	int	no	The total number of times a discount code has been used
status	string	no	enabled, disabled and partially_disabled (disabled at checkout only)
deleted	boolean	no	Refers to is a discount code has been deleted
uses_per_customer	integer	no	Refers to the total number of times a discount code can be used per customer
id_parent	integer	no	The id of the parent discount code in the case of bulk group discount codes
start_date_min	date	no
start_date_max	date	no
end_date_min	date	no
end_date_max	date	no
discount_amount_min	string	no
discount_amount_max	string	no
used_min	integer	no
used_max	integer	no
total_uses_min	integer	no
total_uses_max	integer	no
uses_per_customer_min	integer	no
uses_per_customer_max	integer	no

Manage Subscription

Add Products

POST api/third_party/manage/subscription/orders/{order_id}/products HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "new_order_products": [
     {
       "shopify_product_id": 111111,
       "shopify_variant_id": 222222,
       "quantity": 3,
       "price" : 10.99
     },
     {
       "shopify_product_id": 333333,
       "shopify_variant_id": 444444,
       "quantity": 1,
     },
  ],
  "order_shipping_rate": {
    "code": "Free Shipping",
    "name": "Free Shipping",
    "price": "0.00",
    "source": "shopify",
    "need_change": false,
    "hash": "2abcbdea0deff6e6d85b506c247dbebf4475b41358e023f7b3781230ff423c9c5692c5fcf4f643bfca48bdd0759687e4c3c0401da376ee8da4471a7617f5f43b",
  },
  "one_time": false
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "order_products": [
         {...}, {...}
      ],
      "order_product_exceptions": [
         {...}, {...}
      ],
      "order_shipping_rate": {
         "bold_order_id": 1,
         "code": "Free Shipping",
         "name": "Free Shipping",
         "price": "0.00",
         "source": "shopify",
         "need_change": false,
         "hash": "hash"
      }
   }
}

This endpoint allows you to add products to a subscription. These products can be added as recurring products or added only for the next shipment. You can add a maximum of 20 products at a time. If a product is already on a subscription the quantity would be updated. To add a product as a one time product to just the next shipment then set the flag "one_time" = true in the request body. You can only set the one time flag if you are adding a new product, or adding additional product quantities to the order.

POST api/third_party/manage/subscription/orders/{order_id}/products

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID

Request Body

Element	Sub Element	Type	Description
new_order_products
	shopify_product_id	integer	Shopify Product ID
	shopify_variant_id	integer	Shopify Variant ID
	quantity	integer	Product Quantity
	price	float	The price that should be used for the product. If no price is sent, the price from Shopify will be used.
order_shipping_rate		Object
	bold_order_id	integer	Subscription Order ID
	code	string	Order Shipping Code
	name	string	Order Shipping Name
	price	string	Shipping Price
	source	string	Shipping Source for example: shopify, cashier, decimal etc.
	need_change	integer	0/1
	hash	string	Shipping Hash
one_time		boolean	Add products to next upcoming shipment only

Data Object

Element	Type	Description
id	integer	Subscription Order ID
order_hooks	array	List of Order Hook Objects
order_products	array	List of Order Product Object
order_product_exceptions	array	List of Order Product Exceptions Object
order_shipping_rate	object	Order Shipping Object

Cancel Subscription

DELETE api/third_party/manage/subscription/orders/{order_id}?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
   "cancel_reason": "I want to delete the order"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "Order Deleted",
  "data": {
    "id": 1
  }
}

This endpoint cancels the specified subscription. When a subscription is cancelled we clear all records of order skips and product exceptions. Most subscriptions can be reactivated if you would like orders to process in the future. You can reactivate a subscription through the Bold Subscription admin.

DELETE api/third_party/manage/subscription/orders/{order_id}

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
cancel_reason	string	Reason of cancellation provided by the customer

Data Object

Element	Type	Description
id	integer	Subscription Order ID

Get Cancellation Offers

GET api/third_party/manage/subscription/orders/{order_id}/cancellation_offers?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "id": "1",
  "reasonId": "1",
  "manageOffers": [
    {
      "id": 3,
      "offer_type": 2,
      "discount_code_id": null,
      "cancel_reason_id": 1
    }
  ],
  "discountOffers": [
    {
      "id": 5,
      "type": 2,
      "discount_code": "CANCELCODE",
      "useable_time": 200,
      "only_first_discount": 0,
      "discount_type": 2,
      "discount_amount": "2.00",
      "discount_condition": 0,
      "discount_condition_amount": "0.00",
      "free_shipping_amount": "0.00",
      "free_shipping_country_id": 1,
      "free_shipping_country": "All countries",
      "start_date": "2017-03-24",
      "end_date": "0000-00-00",
      "used": 0,
      "status": 0,
      "deleted": 0,
      "once_per_customer": 0,
      "eligible_product_list": "",
      "id_parent": 0,
      "cancel_id": 1,
      "offer_type": 1,
      "cancel_reason_id": 1
    }
  ]
}

In the Bold Subscriptions admin you can set up difference cancellation flows that your customer wil experience when they go to cancel their subscription. In your cancellation flow you can provide your customers with incentives to keep their subscription, like discount codes they can add to their subscription. This endpoint returns valid cancellation incentives for the given subscription.

GET api/third_party/manage/subscription/orders/{order_id}/cancellation_offers

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
reason_id	integer	Cancellation Reason ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Response Data

Element	Type	Description
id	integer	Subscription Order ID
reasonId	integer	Cancellation Reason ID
manageOffers	array	List of Discount Manage Offers Object
discountOffers	array	List of Discount Offer Objects

Get Subscription Credit Card

GET api/third_party/manage/subscription/orders/{order_id}/card?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "credit_card": {
      "expiry_date": "2020-06-30",
      "last_four": 4532
    }
  }
}

This endpoint gets the basic credit card information associated with the subscription.

GET api/third_party/manage/subscription/orders/{order_id}/card

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Response Data

Element	Sub Element	Type	Description
id		integer	Subscription Order ID
credit_card		array
	expiry_date	date	Credit Card Expiry date
	last_four	integer	Last 4 Credit Card digits

Get Discounts

GET api/third_party/manage/subscription/orders/{order_id}/discounts?customer_id={customer_id}&shop={myshopify_domain}  HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 15,
    "discount": {
      "discount_code": "DISCOUNTCODE",
      "discount_details": "Free shipping to Anywhere up to $100.00 or less"
    },
    "discount_queue": [
      {
        "discount_queue_id": 2,
        "discount_code": "DISCOUNT10",
        "discount_details": "$10.00 off all orders"
      }
    ]
  }
}

This endpoint retrieves discount information for an order.

GET api/third_party/manage/subscription/orders/{order_id}/discounts

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
discount	object	Order Discount Object
discount_queue	array	List of Order Discount Queue Objects

Get Initial Data

GET api/third_party/manage/subscription/initial_data?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "orders": [
         {
            "id": 1,
            "shopify_customer_id": 1,
            "interval_number": 1,
            "interval_type_id": 1,
            "first_name": "FirstName",
            "last_name": "LastName",
            "customer_email": "[email protected]",
            "idempotency_key": "",
            "shopify_cart_token": "1",
            "address1": "Address1",
            "address2": null,
            "country": "Country",
            "province": "Province",
            "city": "City",
            "zip": "Zip",
            "phone": "1111111111",
            "company": "Bold",
            "purchase_date": "2018-06-12",
            "delete_date": null,
            "last_ship_date": "2018-06-12",
            "next_ship_date": "2018-06-12",
            "discount_code_id": 1,
            "cancel_discount_code_id": 0,
            "billing_first_name": "FirstName",
            "billing_last_name": "LastName",
            "billing_address1": "Address1",
            "billing_address2": "Apt 102",
            "billing_country": "Country",
            "billing_province": "Province",
            "billing_city": "City",
            "billing_zip": "Zip",
            "billing_phone": "1111111111",
            "billing_company": "Bold",
            "notes": null,
            "taxes_included": 0,
            "tax_shipping": 0,
            "attributes": "[]",
            "is_cancellable": 1,
            "cancel_reason": null,
            "reactivatable": false,
            "next_active_ship_date": null,
            "billing_plan_id": 0,
            "order_day": null,
            "last_updated": "2018-06-12 11:11:51",
            "order_logs": [
               {
                  "shopify_order_num": "#1",
                  "shopify_order_token": "1",
                  "price": "1.00",
                  "tax": "1.00",
                  "shipping": "1.00",
                  "purchase_date": "2018-06-12",
                  "share_shipping": false,
                  "discount_amount": "0.00",
                  "free_shipping_discount_applied": 0,
                  "charged_amount": "1.00"
               }
            ],
            "order_product_exceptions": [
               {
                  "date": "2018-07-12",
                  "products": [
                     {
                        "product_internal_id": 1,
                        "quantity": 8
                     }
                  ]
               }
            ],
            "order_interval_type": {
               "interval_type": "day",
               "interval_text": "Day",
               "estimated_days": 1
            },
            "order_fixed_recurrences": null,
            "order_products": [
               {
                  "id": 1,
                  "bold_order_id": 1,
                  "product_id": 111,
                  "variant_id": 222,
                  "price": "1.00",
                  "quantity": 1,
                  "gram": 0,
                  "product_title": "ProductTitle",
                  "variant_title": "VariantTitle",
                  "status": 0,
                  "price_changed": 0,
                  "shopify_price": "1.00",
                  "shopify_new_price": null,
                  "sku": "",
                  "shopify_inventory": null,
                  "inventory_management": null,
                  "taxable": 1,
                  "properties": "{\u0022frequency_num\u0022:\u00227\u0022,\u0022frequency_type\u0022:\u00221\u0022,\u0022group_id\u0022:\u00226\u0022,\u0022is_prepaid\u0022:\u0022\u0022,\u0022total_recurrences\u0022:\u0022\u0022,\u0022prepaid_id\u0022:\u0022\u0022,\u0022recurr_after_limit\u0022:\u00221\u0022,\u0022_ro_subscription_box_choices\u0022:[{\u0022slot\u0022:\u002211\u0022,\u0022quantity\u0022:\u00222\u0022},{\u0022slot\u0022:\u002212\u0022,\u0022quantity\u0022:\u00221\u0022}],\u0022_ro_billing_plan\u0022:0,\u0022frequency_type_text\u0022:\u0022Day(s)\u0022}",
                  "vendor": "VendorName",
                  "is_active": true,
                  "last_updated": "2018-06-12 11:06:23",
                  "properties_group_id": 6
               }
            ],
            "order_shipping_rate": {
               "bold_order_id": 1,
               "code": "DOM.EP",
               "name": "ShipName",
               "price": 1.00,
               "source": "shopify",
               "need_change": false,
               "hash": "123"
            },
            "order_exceptions":[
               "2018-08-12",
               "2018-09-12"
            ],
            "order_hooks": [
               {
                  "bold_product_id": 111,
                  "conditions": [
                     {
                        "condition_type": "countdown",
                        "condition_value": "8"
                     }
                  ],
                  "title": "Switch Price",
                  "new_price": null
               }
            ],
            "next_orders": ["2018-06-12",...],
            "is_billing_the_same": true,
            "build_a_box_next_orders": [
               {
                  "date": "2018-06-12",
                  "status": "See details in Build a Box Statuses table",
                  "choices": [
                     {
                        "slot_id": 1,
                        "product_id": 111,
                        "variant_id": 222,
                        "quantity": 1
                     },{...},{...}],
               },{...},{...}
            ],
            "build_a_box": true,
            "has_prepaid": false,
            "group_id": 1,
            "discount": {
               "discount_details": "$0.00 off entire order",
               "discount_code": "SAVE0",
               "discount_uses_per_customer": 2,
               "discount_used_by_customer": 1
            },
            "discount_queue": [
            ],
            "status": 0
         }, {...}, {...}
      ],
      "general_settings": {
         "recurring_type": 2,
         "cancel_mode": 1,
         "provide_cancel_incentives_enabled": false,
         "custom_cancel_message_enabled": false,
         "custom_cancel_message": null,
         "shop_name": "",
         "allow_change_shipping_date": true,
         "allow_change_discounts": true,
         "allow_manage_prepaid": false,
         "bold_token": "123",
         "bold_signature": "123",
         "select_products_url": "https:\/\/test.myshopify.com\/tools\/checkout\/manage_subscription_box\/select_products\/",
         "gateway_name": "",
         "gateway_token": "token"
      },
      "groups":[
         {
            "id":6,
            "frequency_info": {
               "frequency_max": 7,
               "frequency_types": [
                  {
                     "interval_id": 1,
                     "interval_type": "day",
                     "interval_text": "Day",
                     "estimated_days": 1
                  }
               ],
               "is_fixed_interval": true
            }
         },{...},{...}],
      "countries": [
         {
            "code": "CA",
            "country_id": 54200369218,
            "name": "Canada",
            "tax": 0.05,
            "tax_name": "GST"
         },{...},{...}],
      "products": [
         {
            "product_id": 111,
            "handle": "Product1"
         },{...},{...}]
   }
}

This endpoint retrieves all information needed to render a customer portal page for the specified customer.

GET api/third_party/manage/subscription/initial_data

URL Parameters

Element	Type	Description
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Description
orders	Array of all the Initial Data Orders Object associated to a customer
general_settings	General Settings Object containing the Recurring Orders App settings for the shop
groups
countries	List of available countries
products	Array of all products appearing in the orders above

Get Prepaid Settings

GET api/third_party/manage/subscription/orders/{order_id}/prepaid_settings?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "prepaid_settings": {
      "bold_order_id": 1,
      "total_recurrences": 6,
      "recurrence_count": 1,
      "one_charge_only": 0,
      "recurr_after_limit": 0
    }
  }
}

When setting up a subscription group you have the ability to allow customers to prepay for the subscription. This endpoint retrieves information including, but not limited to, how many orders the customer has received, and whether or not the subscription is set to recur after the total number of orders have been processed.

GET api/third_party/manage/subscription/orders/{order_id}/prepaid_settings

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
prepaid_settings	object	Order Fixed Recurrences Object

Get Products

GET api/third_party/manage/subscription/orders/{order_id}/products?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "products": [
         {
            "id": 5,
            "shop_app_id": 1,
            "bold_order_id": 1,
            "product_id": 111,
            "variant_id": 222,
            "price": "10.00",
            "quantity": 1,
            "gram": 100,
            "product_title": "ProductTitle",
            "variant_title": "VariantTItle",
            "status": 0,
            "price_changed": 0,
            "shopify_price": "10.00",
            "shopify_new_price": null,
            "sku": "skuprod1",
            "shopify_inventory": null,
            "inventory_management": "shopify",
            "taxable": 1,
            "properties": "{\u0022frequency_num\u0022:1,\u0022frequency_type\u0022:2,\u0022frequency_type_text\u0022:\u0022Weekx(s***)\u0022,\u0022group_id\u0022:\u00221\u0022,\u0022is_prepaid\u0022:\u0022\u0022,\u0022total_recurrences\u0022:\u0022\u0022,\u0022prepaid_id\u0022:\u0022\u0022,\u0022recurr_after_limit\u0022:\u00220\u0022,\u0022_ro_billing_plan\u0022:0}",
            "vendor": "Vendor",
            "is_active": true,
            "shopify_product": {
               "id": 111,
               "body_html": "",
               "handle": "product_handle",
               "product_type": "",
               "published_scope": "global",
               "title": "ProductTitle",
               "vendor": "vendor",
               "tags": "",
               "options": [
                  {
                     "id": 123,
                     "name": "Title",
                     "position": 1,
                     "product_id": 111,
                     "values": [
                        {
                           "Default Title"
                        }
                     ]
                  }
               ],
               "images":{...},
               "created_at": "2017-02-28T09:41:56+10:30",
               "updated_at": "2017-06-16T02:12:55+09:30",
               "published_at": "2017-02-28T09:35:00+10:30",
               "image": {...},
               "variant": {...}
            }
         }
      ],
      "order": {...},
      "coupon": null,
      "taxes_included": 0,
      "has_prepaid": true
   }
}

This endpoint retrieves all associated products for a subscription.

GET api/third_party/manage/subscription/orders/{order_id}/products

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
products	array	Array of Order Product Objects
order	object	Order Object
coupon	object	Order Discount Object
taxes_included	integer	0 - no / 1 - yes
has_prepaid	boolean	If order is prepaid

Get Shipping Rates

GET api/third_party/manage/subscription/orders/{order_id}/shipping_rates?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "shipping_rates": [
      {
         "code": "DOM.EP",
         "name": "Expedited Parcel",
         "price": "10.00",
         "source": "canada_post",
         "need_change": false,
         "hash": "hash_value"
      },{...},{...}
   ]
}

This endpoint retrieves all the shipping rates that a subscription qualifies for.

GET api/third_party/manage/subscription/orders/{order_id}/shipping_rates

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
shipping_rates	array	List of Order Shipping Rate Objects

Get Upcoming Orders

GET api/third_party/manage/subscription/orders/{order_id}/upcoming?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "has_prepaid": false,
    "next_orders": ["2018-06-20", "2018-06-27", "2018-07-04", "2018-07-11", "2018-07-18", "2018-07-25", "2018-08-01"]
  }
}

This endpoint retrieves a listing of the next upcoming order dates for a subscription.

GET api/third_party/manage/subscription/orders/{order_id}/upcoming

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
has_prepaid	boolean	If order is prepaid
next_orders	array	List of next order dates

Get Upcoming Products

GET api/third_party/manage/subscription/orders/{order_id}/upcoming_products?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
    "status": 200,
    "success": true,
    "message": "OK",
    "data": {
        "id": "1",
        "products": [
            {
                "id": 222,
                "shop_app_id": 1,
                "bold_order_id": 1,
                "product_id": 222,
                "variant_id": 333,
                "price": "10.00",
                "quantity": 1,
                "gram": 0,
                "product_title": "ProductTitle",
                "variant_title": "VariantTitle",
                "status": 0,
                "price_changed": 0,
                "shopify_price": "10.00",
                "shopify_new_price": null,
                "sku": "",
                "shopify_inventory": null,
                "inventory_management": null,
                "taxable": 1,
                "properties": "{\"frequency_num\":\"7\",\"frequency_type\":\"1\",\"group_id\":\"6\",\"is_prepaid\":\"\",\"total_recurrences\":\"\",\"prepaid_id\":\"\",\"recurr_after_limit\":\"1\",\"_ro_subscription_box_choices\":{{\"slot\":\"11\",\"quantity\":\"2\"},{\"slot\":\"12\",\"quantity\":\"1\"}},\"_ro_billing_plan\":0,\"frequency_type_text\":\"Day(s)\"}",
                "vendor": "VendorName",
                "is_active": true,
                "last_updated": "2018-06-12 11:06:23",
                "properties_group_id": null,
                "shopify_product": {
                    "id": 222,
                    "body_html": "123",
                    "handle": "product-handle",
                    "product_type": "",
                    "title": "ProductTitle",
                    "vendor": "VenderName",
                    "tags": "",
                    "images": {
                        {...},{...}
                    },
                    "image": {...},
                    "variant": {...}
                }
            }
        ],
        "order_date": "2018-06-12",
        "has_prepaid": false
    }
}

This endpoint returns the products that will be in an upcoming order for the subscription.

GET api/third_party/manage/subscription/orders/{order_id}/upcoming_products

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
products	array	Array of Order Product Objects
order_date	date	Order Date in Y-m-d format
has_prepaid	boolean	If order is prepaid

Log Attempted Cancellation

POST api/third_party/manage/subscription/orders/{order_id}/cancellation_log?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "cancel_reason": "Too expensive"
}
HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK"
}

This endpoint allows you to add a User Activity Log to the customer history with type "Cancellation Flow Started".

POST api/third_party/manage/subscription/orders/{order_id}/cancellation_log

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
cancel_reason	String	The reason selected for starting the cancellation flow

Pause Subscription

POST api/third_party/manage/subscription/orders/{order_id}/pause?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 99,
    "is_paused": true
  }
}

This endpoint allows the user to pause all orders of that subscription until it is resumed. When a subscription is in a paused state all upcoming orders will be skipped.

POST api/third_party/manage/subscription/orders/{order_id}/pause

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
is_paused	boolean	If subscription is paused

Reactivate Subscription

POST api/third_party/manage/subscription/orders/{order_id}/reactivate?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "next_ship_date": "2020-05-20"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 99,
    "active": true,
    "is_paused": false,
    "next_ship_date": "2020-05-25",
    "reactivatable": false
  }
}

This endpoint allows the user to reactivate a subscription that was cancelled in the past. This endpoint will only work for subscriptions that have the reactivatable property set to true. Prepaid and limited length subscriptions are not reactivatable. You can optionally send the next_ship_date for the date you would like the next order to generate, if no date is sent, then the current date will be used.

POST api/third_party/manage/subscription/orders/{order_id}/reactivate

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Description
next_ship_date	Next date order should generate in the Y-m-d format

Data Object

Element	Type	Description
id	integer	Subscription Order ID
active	date	Subscription active status
is_paused	boolean	Subscription is paused status
next_ship_date	array	Next date order will generate
reactivatable	boolean	Status on if a subscription can be reactivated

Recover Order

POST api/third_party/manage/subscription/orders/{order_id}/recover?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "order_date": "2018-06-20"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "next_active_ship_date": "2018-06-20",
    "order_exceptions": {}
  }
}

This endpoint allows you to un skip an order that was previously set to be skipped for a given order date.

POST api/third_party/manage/subscription/orders/{order_id}/recover

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Description
order_date	recover date in the Y-m-d format

Data Object

Element	Type	Description
id	integer	Subscription Order ID
next_active_ship_date	date	Next Active Order Date
order_exceptions	array	List of order exceptions

Resume Subscription

POST api/third_party/manage/subscription/orders/{order_id}/resume?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 99,
    "is_paused": false
  }
}

This endpoint allows the user to resume a paused subscription. We will start to process orders again according to the next ship date for the subscription.

POST api/third_party/manage/subscription/orders/{order_id}/resume

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
is_paused	boolean	If subscription is paused

Save Build-a-Box Choices

POST api/third_party/manage/subscription/orders/{order_id}/build_a_box_choices?customer_id={customer_id} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "order_date":"2019-11-15",
    "choices": [
  	    {
  	        "slot_id": 1,
  	        "quantity": 1
  	    },
  	    {
  	        "slot_id": 2,
  	        "quantity": 2
  	    }
  ]
}

HTTPS/1.1 200 OK

Example response

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "orders": [
      {
        "id": 1,
        "shopify_customer_id": 1234,
        "interval_number": 1,
        "interval_type_id": 1,
        "first_name": "Marie",
        "last_name": "Curie",
        "customer_email": "[email protected]",
        "gateway_payment_method_id": "",
        "address1": "50 Fultz blvd",
        "address2": null,
        "country": "Canada",
        "province": "Manitoba",
        "city": "Winnipeg",
        "zip": "R3Y 0L6",
        "phone": "5555555555",
        "company": "",
        "purchase_date": "2019-10-25",
        "last_ship_date": "2019-10-25",
        "next_ship_date": "2019-11-12",
        "active": true,
        "discount_code_id": 0,
        "cancel_discount_code_id": 0,
        "billing_first_name": "Marie",
        "billing_last_name": "Curie",
        "billing_address1": "50 Fultz blvd",
        "billing_address2": null,
        "billing_country": "Canada",
        "billing_province": "Manitoba",
        "billing_city": "Winnipeg",
        "billing_zip": "R3Y 0L6",
        "billing_phone": "5555555555",
        "billing_company": "",
        "notes": null,
        "taxes_included": 0,
        "tax_shipping": 1,
        "attributes": "[]",
        "is_cancellable": true,
        "cancel_reason": null,
        "reactivatable": false,
        "next_active_ship_date": "2019-10-26",
        "billing_plan_id": 0,
        "order_day": null,
        "last_updated": "2019-11-13 08:49:11",
        "shopify_order_tags": null,
        "is_paused": false,
        "currency": "",
        "currency_exchange_rate": "1.000000000000",
        "currency_format": null,
        "order_products": [
          {
            "id": 2530,
            "bold_order_id": 1,
            "product_id": 1574423429210,
            "variant_id": 15434163224666,
            "price": "10.00",
            "quantity": 1,
            "gram": 0,
            "product_title": "BUILD A BOX",
            "variant_title": "Default Title",
            "status": 0,
            "price_changed": 0,
            "shopify_price": "10.00",
            "shopify_new_price": null,
            "sku": "",
            "shopify_inventory": null,
            "inventory_management": null,
            "taxable": 1,
            "properties": "{\"frequency_num\":\"1\",\"frequency_type\":\"1\",\"group_id\":\"6\",\"is_prepaid\":\"\",\"total_recurrences\":\"\",\"prepaid_id\":\"\",\"recurr_after_limit\":\"1\",\"_ro_subscription_box_choices\":[{\"slot\":\"1\",\"quantity\":\"3\"},{\"slot\":\"2\",\"quantity\":\"0\"}],\"_ro_billing_plan\":0,\"frequency_type_text\":\"Day(s)\"}",
            "vendor": "test-shop",
            "is_active": true,
            "last_updated": "2019-10-25 13:16:39",
            "converted_price": 0,
            "properties_group_id": 6
          }
        ],
        "order_fixed_recurrences": null,
        "next_orders": [
          "2019-11-12",
          "2019-11-13",
          "2019-11-14",
          "2019-11-15",
          "2019-11-16",
          "2019-11-17",
          "2019-11-18"
        ],
        "build_a_box": true,
        "build_a_box_next_orders": [
          {
            "date": "2019-11-12",
            "status": "build_a_box_locked_default_choices",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 2
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 1
              }
            ]
          },
          {
            "date": "2019-11-13",
            "status": "build_a_box_locked_default_choices",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 2
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 1
              }
            ]
          },
          {
            "date": "2019-11-14",
            "status": "build_a_box_locked_default_choices",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 2
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 1
              }
            ]
          },
          {
            "date": "2019-11-15",
            "status": "build_a_box_available_choices_made",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 1
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 2
              }
            ]
          },
          {
            "date": "2019-11-16",
            "status": "build_a_box_available",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 2
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 1
              }
            ]
          },
          {
            "date": "2019-11-17",
            "status": "build_a_box_unavailable",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 2
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 1
              }
            ]
          },
          {
            "date": "2019-11-18",
            "status": "build_a_box_unavailable",
            "choices": [
              {
                "slot_id": 1,
                "product_id": 1649329406042,
                "variant_id": 16089077022810,
                "quantity": 2
              },
              {
                "slot_id": 2,
                "product_id": 1649345200218,
                "variant_id": 16089118081114,
                "quantity": 1
              }
            ]
          }
        ],
        "is_price_based_on_choices": false
      }
    ]
  }
}

This endpoint allows you to save selections for an order date, for a Build-a-Box subscription. This endpoint respects the lock settings, of the subscription group.

POST api/third_party/manage/subscription/orders/{order_id}/build_a_box_choices

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID

Request Body

Element	Type	Description
order_date	date	Upcoming order date
choices	array	Array of selected choices for build-a-box slots

Response Data

Element	Type	Description
orders	array	List of Order objects
order_products	array	List of Order Product Objects
build_a_box_next_orders	array	List of Build-a-Box Objects

Save Cancellation Offer Code

POST api/third_party/manage/subscription/orders/{order_id}/cancellation_offer_code?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "discount_code": "CANCELCODE",
    "reason_id": 1
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": "1",
    "cancel_discount_code_id": 1,
    "message": "Order Updated"
  }
}

This endpoint applies cancellation discount code to the given order.

POST api/third_party/manage/subscription/orders/{order_id}/cancellation_offer_code

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
discount_code	string	Discount Code
reason_id	integer	Cancellation Reason ID

Data Object

Element	Type	Description
id	integer	Subscription Order ID
cancel_discount_code_id	integer	Cancel Discount Code ID
message	string	Response message

Save Discount

POST api/third_party/manage/subscription/orders/{order_id}/discount?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "discount_code": "DISCOUNTCODE"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 15,
    "discount": {
      "discount_code": "DISCOUNTCODE",
      "discount_details": "Free shipping to Anywhere up to $100.00 or less"
    },
    "discount_queue": [
      {
        "discount_queue_id": 2,
        "discount_code": "DISCOUNTCODE2",
        "discount_details": "$10.00 off all orders"
      }
    ]
  }
}

This endpoint adds or updates existing discount code for a subscription.

POST api/third_party/manage/subscription/orders/{order_id}/discount

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
discount_code	string	Discount code

Data Object

Element	Type	Description
id	integer	Subscription Order ID
discount	object	Order Discount Object
discount_queue	array	List of Order Discount Queue Objects

Save Swap Product

PUT api/third_party/manage/subscription/orders/{order_id}/save_swap_product?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "order_id": 1,
    "product_internal_id": 1,
    "product_id": 123456789,
    "variant_id": 234567891,
   "order_shipping_rate": {
      "code": "DOM.EP",
      "name": "Expedited Parcel",
      "source": "canada_post",
      "price": "2312.10",
      "need_change": false,
      "hash": "hash"
   }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "order_products": [
         {
            "id": 1,
            "bold_order_id": 1,
            "product_id": 123456789,
            "variant_id": 234567891,
            "price": "5.00",
            "quantity": 1,
            "gram": 0,
            "product_title": "SwappedProductTitle",
            "variant_title": "SwappedVariantTitle",
            "status": 0,
            "price_changed": 0,
            "shopify_price": "1.00",
            "shopify_new_price": null,
            "sku": "",
            "shopify_inventory": null,
            "inventory_management": null,
            "taxable": 1,
            "properties": "{\u0022frequency_num\u0022:\u00227\u0022,\u0022frequency_type\u0022:\u00221\u0022,\u0022group_id\u0022:\u00226\u0022,\u0022is_prepaid\u0022:\u0022\u0022,\u0022total_recurrences\u0022:\u0022\u0022,\u0022prepaid_id\u0022:\u0022\u0022,\u0022recurr_after_limit\u0022:\u00221\u0022,\u0022_ro_subscription_box_choices\u0022:[{\u0022slot\u0022:\u002211\u0022,\u0022quantity\u0022:\u00222\u0022},{\u0022slot\u0022:\u002212\u0022,\u0022quantity\u0022:\u00221\u0022}],\u0022_ro_billing_plan\u0022:0,\u0022frequency_type_text\u0022:\u0022Day(s)\u0022}",
            "vendor": "VendorName",
            "is_active": true,
            "last_updated": "2018-06-12 11:06:23",
            "properties_group_id": 6
         },
         {...}
      ],
      "order_shipping_rate": {
         "code": "DOM.EP",
         "name": "Expedited Parcel",
         "source": "canada_post",
         "price": "2312.10",
         "need_change": false,
         "hash": "hash"
      }
   }
}

This endpoint will swap a product on an order with the product indicated by the product id and variant id. You must send a valid shipping rate for the subscription that was calculated with the new product.

PUT api/third_party/manage/subscription/orders/{order_id}/save_swap_product

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Sub Element	Type	Description
product_internal_id		integer	Recurring Orders internal product ID for the product being replaced.
product_id		integer	Shopify product ID for the swap product.
variant_id		integer	Shopify variant ID for the swap product.
order_shipping_rate		object
	code	string	Order Shipping Code
	name	string	Order Shipping Name
	price	string	Shipping Price
	source	string	Shipping Source for example: shopify, cashier, decimal etc.
	need_change	integer	0/1
	hash	string	shipping Hash

Response Data

Element	Type	Description
id	integer	Subscription Order ID
order_products	array	List of Order Product Objects
order_shipping_rate	object	Order Shipping Object

Save Upcoming Products

PUT api/third_party/manage/subscription/orders/{order_id}/upcoming_products?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "order_date": "2017-06-01",
    "order_products": [
       {
          "product_internal_id": 1,
          "quantity": 1
       },
       {
          "product_internal_id": 2,
          "quantity": 1
       },
       {
          "product_internal_id": 3,
          "quantity": 0
       }
   ],
   "order_shipping_rate": {
      "code": "DOM.EP",
      "name": "Expedited Parcel",
      "source": "canada_post",
      "price": "2312.10",
      "need_change": false,
      "hash": "hash"
   }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 145,
    "order_product_exceptions": [
      {
        "date": "2017-06-01",
        "products": [
          {
            "product_internal_id": 1,
            "quantity": 1
          },
          {
            "product_internal_id": 2,
            "quantity": 1
          },
          {
            "product_internal_id": 3,
            "quantity": 0
          }
        ]
      }
    ]
  }
}

This endpoint updates products quantity for a specific upcoming order for the subscription.

PUT api/third_party/manage/subscription/orders/{order_id}/upcoming_products

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Sub Element	Type	Description
order_date		date	Order Date in Y-m-d format
order_products		array
	product_internal_id	integer	Recurring Orders internal product ID
	quantity	integer	Product quantity
order_shipping_rate		Object
	code	string	Order Shipping Code
	name	string	Order Shipping Name
	price	string	Shipping Price
	source	string	Shipping Source for example: shopify, cashier, decimal etc.
	need_change	integer	0/1
	hash	string	shipping Hash

Response Data

Element	Type	Description
id	integer
order_product_exceptions	array	List of Order Product Exceptions Object

Skip Order

POST api/third_party/manage/subscription/orders/{order_id}/skip?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "order_date": "2018-06-20"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 15,
    "next_active_ship_date": "2018-06-27",
    "order_exceptions": ["2018-06-20"]
  }
}

This endpoint allows to add order exception date. When this order goes to process it will be skipped. The order will not be placed in Shopify, and the next ship date will be advanced for the subscription.

POST api/third_party/manage/subscription/orders/{order_id}/skip

URL Parameters

Element	Type	Description
shop	string	myshopify url
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Description
order_date	skip date in the Y-m-d format

Data Object

Element	Type	Description
id	integer	Subscription Order ID
next_active_ship_date	date	Next Active Order Date
order_exceptions	array	List of order exceptions

Update Billing Address

PUT api/third_party/manage/subscription/orders/{order_id}/billing_address?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "billing_address": {
    "billing_first_name": "John",
    "billing_last_name": "Doe",
    "billing_address1": "123 Not Real St.",
    "billing_address2": "",
    "billing_country": "CA",
    "billing_province": "MB",
    "billing_city": "Winnipeg",
    "billing_zip": "R3T 0H4",
    "billing_phone": "",
    "billing_company": ""
  }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "billing_first_name": "John",
    "billing_last_name": "Doe",
    "billing_address1": "123 Not Real St.",
    "billing_address2": null,
    "billing_country": "CA",
    "billing_province": "MB",
    "billing_city": "Winnipeg",
    "billing_zip": "R3T 0H4",
    "billing_phone": "",
    "billing_company": ""
  }
}

This endpoint updates the billing address for subscription.

PUT api/third_party/manage/subscription/orders/{order_id}/billing_address

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Sub Element	Type	Description
billing_address		Object
	billing_first_name	string	Billing First name
	billing_last_name	string	Billing Last name
	billing_address1	string	Billing Address
	billing_address2	string	Billing Address optional
	billing_country	string	Billing Country
	billing_company	string	Billing Company
	billing_province	string	Billing Province
	billing_city	string	Billing City
	billing_zip	string	Billing Zip code
	billing_phone	string	Billing Phone number

Data Object

Element	Type	Description
id	integer	Subscription Order ID
billing_first_name	string	Billing First Name
billing_last_name	string	Billing Last name
billing_address1	string	Billing Address
billing_address2	string	Billing Address optional
billing_country	string	Billing Country
billing_province	string	Billing Province
billing_city	string	Billing City
billing_zip	string	Billing Zip Code
billing_phone	string	Billing Phone Number
billing_company	string	Billing Company

Update Next Order Date

PUT api/third_party/manage/subscription/orders/{order_id}/next_ship_date?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
   "next_shipping_date": "2018-06-20"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
    "status": 200,
    "success": true,
    "message": "OK",
    "data": {
        "id": 1,
        "next_ship_date": "2018-06-20",
        "next_orders": {
            "2018-06-20",
            "2018-06-27",
            "2018-07-04",
            "2018-07-11",
            "2018-07-18",
            "2018-07-25",
            "2018-08-01",
        },
        "build_a_box_next_orders" : [],
        "order_product_exceptions": [],
        "order_exceptions": [],
        "message": "Upcoming order date was changed."
    }
}

This endpoint updates next order date for subscription.

PUT api/third_party/manage/subscription/orders/{order_id}/next_ship_date

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
next_shipping_date	string	Next order date in the Y-m-d format

Data Object

Element	Type	Description
id	integer	Subscription Order ID
next_ship_date	date	Next order date in the Y-m-d format
next_orders	date	Next orders date in the Y-m-d format
build_a_box_next_orders	date	Next orders date and selections if the type is build a box
order_exceptions	array	Array of order exception dates
order_product_exceptions	array	List of Order Product Exceptions Object
message	string	Message with translations

Update Subscription Interval

PUT api/third_party/manage/subscription/orders/{order_id}/interval?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
   "frequency_type": "1",
   "frequency_num": "7"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "interval_number": 7,
      "interval_type_id": 1,
      "next_ship_date": "2018-06-12",
      "next_orders": {
         "2018-06-12",
         "2018-06-19",
         "2018-06-26",
         "2018-07-03",
         "2018-07-10",
         "2018-07-17",
         "2018-07-24"
      },
      "order_exceptions": {}
   }
}

This endpoint updates order interval for a subscription. When you update the subscription interval all order exceptions (e.g. skipped orders), will be removed.

PUT api/third_party/manage/subscription/orders/{order_id}/interval

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
frequency_type	integer	Recurring interval type: 1 - Day 2 - Week 3 - Month 5 - Year
frequency_num	integer	Recurring interval number for example: 2 (for every 2 weeks/days etc.)

Data Object

Element	Description
id	Subscription Order ID
interval_number	Recurring interval number
interval_type_id	Recurring interval type
next_ship_date	Next order date in date string Y-m-d
next_orders	The array of new next order dates
order_exceptions	The array of order exceptions dates

Update Prepaid Settings

PUT api/third_party/manage/subscription/orders/{order_id}/prepaid_settings?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "prepaid_settings": {
     "recurr_after_limit": 1
  }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "prepaid_settings": {
      "total_recurrences": 6,
      "recurrence_count": 1,
      "one_charge_only": 0,
      "recurr_after_limit": 1
    }
  }
}

This endpoint updates the prepaid settings for specific order.

PUT api/third_party/manage/subscription/orders/{order_id}/prepaid_settings

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Sub Element	Type	Description
prepaid_settings		object
	recurr_after_limit	integer	Automatically renew after last prepaid order Allowed: 0 / 1

Response Data

Element	Type	Description
id	integer	Subscription Order ID
prepaid_settings	object	Order Fixed Recurrences Object

Update Quantity

PUT api/third_party/manage/subscription/orders/{order_id}/quantity?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "order_products": [
     {
       "product_internal_id": 1,
       "quantity": 3,
       "is_deleted": false
     },
     {
       "product_internal_id": 2,
       "quantity": 2,
       "is_deleted": false
     },
     {
       "product_internal_id": 3,
       "quantity": 0,
       "is_deleted": false
     }
  ],
  "order_shipping_rate": {
    "code": "Free Shipping",
    "name": "Free Shipping",
    "price": "0.00",
    "source": "shopify",
    "need_change": false,
    "hash": "2abcbdea0deff6e6d85b506c247dbebf4475b41358e023f7b3781230ff423c9c5692c5fcf4f643bfca48bdd0759687e4c3c0401da376ee8da4471a7617f5f43b",
  }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "order_products": [
         {...}, {...}
      ],
      "order_product_exceptions": [
         {...}, {...}
      ],
      "order_shipping_rate": {
         "bold_order_id": 1,
         "code": "Free Shipping",
         "name": "Free Shipping",
         "price": "0.00",
         "source": "shopify",
         "need_change": false,
         "hash": "hash"
      }
   }
}

This endpoint updates the quantity of specified products in the subscription for the remainder of the subscription.

PUT api/third_party/manage/subscription/orders/{order_id}/quantity

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Sub Element	Type	Description
order_products
	product_internal_id	integer	Recurring Orders internal product ID
	quantity	integer	Product quantity
	is_deleted	boolean	true/false
order_shipping_rate		Object
	bold_order_id	integer	Subscription Order ID
	code	string	Order Shipping Code
	name	string	Order Shipping Name
	price	string	Shipping Price
	source	string	Shipping Source for example: shopify, cashier, decimal etc.
	need_change	integer	0/1
	hash	string	shipping Hash

Data Object

Element	Type	Description
id	integer	Subscription Order ID
order_products	array	List of Order Product Object
order_product_exceptions	array	List of Order Product Exceptions Object
order_shipping_rate	object	Order Shipping Object

Update Shipping Address

PUT api/third_party/manage/subscription/orders/{order_id}/shipping_address?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Not Real St.",
    "address2": "",
    "country": "CA",
    "province": "MB",
    "city": "Winnipeg",
    "zip": "R3T 0H4",
    "phone": ""
  },
  "order_shipping_rate": {
    "bold_order_id": 1,
    "code": "Canada Post",
    "name": "Canada Post",
    "price": "10.00",
    "source": "cashier",
    "need_change": 0,
    "hash": "73c168a51022850a4d1ca9f863c5bf29d911c292feaddeac0228f8d8908cce7ac9554a310972832b841e08b6e0d3fe489d7170819ea77bdcea1b2eba56856e81"
    }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Not Real St.",
    "address2": "",
    "country": "CA",
    "province": "MB",
    "city": "Winnipeg",
    "zip": "R3T 0H4",
    "phone": "",
    "company": "",
    "order_shipping_rate": {
      "bold_order_id": 1,
      "code": "Canada Post",
      "name": "Canada Post",
      "price": "10",
      "source": "cashier",
      "need_change": false,
      "hash": "33c83de87223252049549928fdbd133762a07db4d18073ca1620016591aa02c5c8965f1e2a24f224cb6cfdecf3fa097f0b7ab375d5a7d13e4fa46fd94e71bd36"
    }
  }
}

This endpoint updates the shipping address for a subscription.

PUT api/third_party/manage/subscription/orders/{order_id}/shipping_address

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Sub Element	Type	Description
shipping_address		Object
	first_name	string	Shipping First name
	last_name	string	Shipping Last name
	address1	string	Shipping Address
	address2	string	Shipping Address optional
	country	string	Shipping Country
	company	string	Shipping Company
	province	string	Shipping Province
	city	string	Shipping City
	zip	string	Shipping Zip code
	phone	string	Shipping Phone number
order_shipping_rate		Object
	code	string	Order Shipping Code
	name	string	Order Shipping Name
	price	string	Shipping Price
	source	string	Shipping Source for example: shopify, cashier, decimal etc.
	need_change	integer	0/1
	hash	string	shipping Hash

Data Object

Element	Type	Description
id	integer	Subscription Order ID
first_name	string	Shipping First Name
last_name	string	Shipping Last name
address1	string	Shipping Address
address2	string	Shipping Address optional
country	string	Shipping Country
province	string	Shipping Province
city	string	Shipping City
zip	string	Shipping Zip Code
phone	string	Shipping Phone Number
company	string	Shipping Company
order_shipping_rate	object	Order Shipping Object

Update Shipping Method

PUT api/third_party/manage/subscription/orders/{order_id}/shipping_method?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "order_shipping_rate": {
        "code": "NEWSHIP",
        "name": "new shipping method",
        "price": "10.00",
        "source": "new_source",
        "need_change": 0,
        "hash": "hashValue"
    }
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "success": true,
  "status": 200,
  "message": "OK",
  "data": {
    "id": 1,
    "order_shipping_rate": {
      "code": "NEWSHIP",
      "name": "new shipping method",
      "price": "10.00",
      "source": "new_source",
      "need_change": 0,
      "hash": "hashValue"
    }
  }
}

This endpoint updates the shipping method for a subscription.

PUT api/third_party/manage/subscription/orders/{order_id}/shipping_method

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Body Request

Element	Sub Element	Type	Description
order_shipping_rate		Object
	code	string	Order Shipping Code
	name	string	Order Shipping Name
	price	string	Shipping Price
	source	string	Shipping Source for example: shopify, cashier, decimal etc.
	need_change	integer	0/1
	hash	string	shipping Hash

Data Object

Element	Type	Description
id	integer	Subscription Order ID
order_shipping_rate	object	Order Shipping Object

Update Shopify Order Tags

PUT api/third_party/manage/subscription/orders/{order_id}/shopify_order_tags?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
"shopify_order_tags" : "initial_order,new_subscriber"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "shopify_order_tags": "initial_order,new_subscriber"
  }
}

This endpoint updates the order tags in Shopify for the subscription. This will only apply to future orders.

PUT api/third_party/manage/subscription/orders/{order_id}/shopify_order_tags

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
shopify_order_tags	string	A comma separated string of all the tags that are to be applied to the upcoming orders

Data Object

Element	Type	Description
id	integer	Subscription Order ID
shopify_order_tags	string	A comma separated string of all the tags that are to be applied to the upcoming orders

Get Swap Information From Group

GET api/third_party/manage/subscription/groups/{group_id}/swap_information?product_internal_id={product_internal_id}&order_id={order_id}&customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
   "status": 200,
   "success": true,
   "message": "OK",
   "data": {
      "id": 1,
      "product_internal_id": 1,
      "products_with_price_difference": [
         {
            "handle": "product-handle-test",
            "product_id": 123456789,
            "shopify_data": {...},
         },
         {...}
      ]
   }
}

This endpoint retrieves all swap information for a subscription group id, internal product id and order id.

GET api/third_party/manage/subscription/groups/{group_id}/swap_information

URL Parameters

Element	Type	Description
group_id	integer	Subscription Group ID
product_internal_id	integer	Internal Product ID
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID
product_internal_id	integer	Subscription Order Product ID
products_with_price_difference	array	Array of products with price differences (Shopify Product Object)

Subscription Groups

Get

GET /api/third_party/subscription_groups?shop={myshopifyDomain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

{
  "subscription_groups": [
    {
      "id": 1,
      "shop_app_id": 3,
      "group_name": "Bob's Burgers",
      "subscription_type": 1,
      "filter": "{\"select\":1,\"products\":[{\"prod_id\":\"691778060343\",\"id\":\"8291055108151\"}]}",
      "group_discount": "0.0000",
      "visible": true,
      "max_number": 6,
      "min_recurrences_before_cancellable": 0,
      "pause_filter": "{\"select\":0,\"products\":[]}",
      "is_paused": 0,
      "interval_type": 0,
      "subscription_only": 0,
      "total_recurrences": 0,
      "is_limited_subscription": 0,
      "limited_continue": 1,
      "allow_one_payment": 0,
      "prepaid_continue": 1,
      "is_prepaid_only": 0,
      "is_prepaid_always_expires": 0,
      "allow_is_gift": 0,
      "billing_plan": 0,
      "billing_day": 0,
      "billing_offset": 0,
      "allow_swap": 0,
      "include_free_gift": 0,
      "gift_filter": "",
      "allow_ongoing": 0,
      "apply_secondary_discount_on_product_swap": 0,
      "affected_products": [
        {
          "group_id": 1,
          "variant_id": 8291055108151
        },
        {
          "group_id": 1,
          "variant_id": 8291055108151
        }
      ],
      "intervals": [
        {
          "interval_id": 1
        },
        {
          "interval_id": 2
        },
        {
          "interval_id": 3
        },
        {
          "interval_id": 5
        },
        {
          "interval_id": 1
        },
        {
          "interval_id": 2
        },
        {
          "interval_id": 3
        },
        {
          "interval_id": 5
        }
      ]
    },
    {
      "id": 3,
      "shop_app_id": 3,
      "group_name": "another test",
      "subscription_type": 1,
      "filter": "{\"select\":1,\"products\":[{\"prod_id\":\"691778060343\",\"id\":\"8291055108151\"}]}",
      "group_discount": "0.0000",
      "visible": true,
      "max_number": 9,
      "min_recurrences_before_cancellable": 0,
      "pause_filter": null,
      "is_paused": 0,
      "interval_type": 0,
      "subscription_only": 0,
      "total_recurrences": 0,
      "is_limited_subscription": 0,
      "limited_continue": 1,
      "allow_one_payment": 0,
      "prepaid_continue": 1,
      "is_prepaid_only": 0,
      "is_prepaid_always_expires": 0,
      "allow_is_gift": 0,
      "billing_plan": 0,
      "billing_day": 0,
      "billing_offset": 0,
      "allow_swap": 0,
      "include_free_gift": 0,
      "gift_filter": "",
      "allow_ongoing": 0,
      "apply_secondary_discount_on_product_swap": 0,
      "affected_products": [],
      "intervals": [
        {
          "interval_id": 3
        }
      ]
    },
    {
      "id": 4,
      "shop_app_id": 3,
      "group_name": "Tim's Tulips",
      "subscription_type": 1,
      "filter": "{\"select\":0,\"products\":[]}",
      "group_discount": "0.0000",
      "visible": true,
      "max_number": 6,
      "min_recurrences_before_cancellable": 0,
      "pause_filter": "{\"select\":1,\"products\":[{\"prod_id\":\"691778060343\",\"id\":\"8291055108151\"}]}",
      "is_paused": 1,
      "interval_type": 0,
      "subscription_only": 0,
      "total_recurrences": 0,
      "is_limited_subscription": 0,
      "limited_continue": 1,
      "allow_one_payment": 0,
      "prepaid_continue": 1,
      "is_prepaid_only": 0,
      "is_prepaid_always_expires": 0,
      "allow_is_gift": 0,
      "billing_plan": 0,
      "billing_day": 0,
      "billing_offset": 0,
      "allow_swap": 0,
      "include_free_gift": 0,
      "gift_filter": "",
      "allow_ongoing": 0,
      "apply_secondary_discount_on_product_swap": 0,
      "affected_products": [],
      "intervals": [
        {
          "interval_id": 1
        },
        {
          "interval_id": 2
        },
        {
          "interval_id": 3
        },
        {
          "interval_id": 5
        },
        {
          "interval_id": 1
        },
        {
          "interval_id": 2
        },
        {
          "interval_id": 3
        },
        {
          "interval_id": 5
        }
      ]
    }
  ]
}

This endpoint retrieves a list of all subscription groups created by the store.

GET /api/third_party/subscription_groups?shop={myshopifyDomain}

URL Parameters

Element	Type	Description
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description

Element descriptions pending...

Subscriptions

Get

GET /api/third_party/v2/subscriptions?shop={myshopifyDomain}&since_id={since_id}&limit={limit} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

{
  "subscriptions": [
    {
      "id": 3,
      "shopify_customer_id": 267534937,
      "interval_number": 1,
      "interval_type_id": 1,
      "first_name": "Donnie",
      "last_name": "Blasco",
      "customer_email": "[email protected]",
      "address1": "511 meadowlark",
      "address2": null,
      "country": "Canada",
      "province": "Manitoba",
      "city": "Ile Des Chenes",
      "zip": "R0A 0T0",
      "phone": "250-555-3413",
      "company": "",
      "purchase_date": "2018-06-28",
      "delete_date": null,
      "last_ship_date": "2018-06-28",
      "next_ship_date": "2018-06-29",
      "active": false,
      "is_paused": true,
      "discount_code_id": 0,
      "cancel_discount_code_id": 0,
      "billing_first_name": "Donnie",
      "billing_last_name": "Blasco",
      "billing_address1": "511 meadowlark",
      "billing_address2": null,
      "billing_country": "Canada",
      "billing_province": "Manitoba",
      "billing_city": "Ile Des Chenes",
      "billing_zip": "R0A 0T0",
      "billing_phone": "250-555-3413",
      "billing_company": "",
      "notes": null,
      "shopify_order_tags": null,
      "taxes_included": 0,
      "tax_shipping": 0,
      "currency": "",
      "currency_exchange_rate": "1.000000000000",
      "currency_format": "",
      "attributes": "[]",
      "is_cancellable": true,
      "cancel_reason": null,
      "reactivatable": false,
      "next_active_ship_date": "2018-06-29",
      "billing_plan_id": 0,
      "order_day": null,
      "last_updated": "2018-06-28 11:22:07",
      "paused_date": "2018-06-28 10:18:46",
      "order_products": [
        {
          "id": 3,
          "bold_order_id": 3,
          "product_id": 691777929271,
          "variant_id": 8291054583863,
          "price": "1040.00",
          "quantity": 1,
          "gram": 0,
          "product_title": "1.50ctw Diamond 14k Gold Wedding Band Eternity Ring",
          "variant_title": "Default Title",
          "status": 0,
          "price_changed": 0,
          "shopify_price": "1300.00",
          "shopify_new_price": null,
          "sku": "14522",
          "shopify_inventory": null,
          "inventory_management": null,
          "taxable": 1,
          "properties": "{\"frequency_num\":\"1\",\"frequency_type\":\"1\",\"group_id\":\"2\",\"is_prepaid\":\"1\",\"total_recurrences\":\"3\",\"prepaid_id\":\"2\",\"recurr_after_limit\":0,\"_ro_subscription_box_choices\":[],\"_ro_billing_plan\":0,\"frequency_type_text\":\"Day(s)\"}",
          "vendor": "Not Signed",
          "is_active": true,
          "last_updated": "2018-06-28 11:22:06",
          "properties_group_id": null,
          "order_product_exceptions": []
        }
      ],
      "order_fixed_recurrences": {
        "bold_order_id": 3,
        "total_recurrences": 5,
        "recurrence_count": 1,
        "one_charge_only": 1,
        "recurr_after_limit": 0,
        "last_updated": "2018-07-17 17:16:38"
      },
      "order_exceptions": [],
      "order_logs": [
        {
          "id": 3,
          "shopify_order_num": "#2257",
          "shopify_order_token": "17fddcd6290183b5b7c97f65919995e5",
          "price": "3120.00",
          "tax": "405.60",
          "shipping": "28.50",
          "purchase_date": "2018-06-28",
          "share_shipping": false,
          "discount_amount": "0.00",
          "free_shipping_discount_applied": 0,
          "charged_amount": "3554.10"
        }
      ],
      "order_log_failed_transactions": [],
      "order_shipping_rate_exceptions": []
    }
  ]
}

This endpoint retrieves a filtered page of the store's subscriptions. This endpoint is paginated, returning a page with 50 results. To retrieve the next page of results use the greatest subscription id in a subsequent request.

GET /api/third_party/v2/subscriptions?shop={myshopifyDomain}&since_id={since_id}&limit={limit}

URL Parameters

Element	Type	Required	Description
shop	string	yes	The store's Shopify domain, e.g. mystore.myshopify.com
since_id	int	yes	RO will return all orders greater than the number specified. For the first page you should set it to 0.
limit	int	no	The cursor's size. This can be set with any number between 1 to 50.
id	integer	no	Bold's internal subscription id.
customer_email	string	no	the customer email associated with this subscription.
active	boolean	no	Show subscriptions filtered on their active status
is_paused	boolean	no	Show subscriptions filtered on their paused status
cancel_reason	string	no	Show subscriptions filtered on their cancel reason
shopify_customer_id	big int	no	Show subscriptions based on the customer's Shopify unique id.
first_name	string	no	Show subscriptions filtered by shipping first name
last_name	string	no	Show subscriptions filtered by shipping last name
phone	string	no	Show subscriptions filtered by phone
address1	string	no	Show subscriptions filtered by shipping address 1
address2	string	no	Show subscriptions filtered by shipping address 2
country	string	no	Show subscriptions filtered by shipping country
province	string	no	Show subscriptions filtered by shipping province/state
zip	string	no	Show subscriptions filtered on shipping zip/postal code
purchase_date	string	no	Show subscriptions filtered on the original purchase date of the subscription
last_ship_date	date	no	Show subscriptions filtered by the most recent Shopify order date.
next_ship_date	date	no	Show subscriptions filtered by the next upcoming Shopify order date.
discount_code_id	big int	no	Show subscriptions filtered by the ID of the discount code used on this subscription.
billing_first_name	string	no	Show subscriptions filtered on the billing first name
billing_last_name	string	no	Show subscriptions filtered on the billing last name
billing_address1	string	no	Show subscriptions filtered on billing address 1
billing_country	string	no	Show subscriptions filtered on billing address 2
billing_province	string	no	Show subscriptions filtered on billing province
billing_zip	string	no	Show subscriptions filtered on billing zip/postal code
billing_phone	string	no	Show subscriptions filtered on billing phone
taxes_included	boolean	no	Show subscriptions filtered whether taxes were applied to the subscription.
tax_shipping	boolean	no	Show subscriptions filtered whether taxes were applied to the shipping lines.
next_active_ship_date	date	no	Show subscriptions filtered on next ship date, taking order exceptions into account. (Example: If a customer has skipped the next two recurrences, the next active ship date will reflect the date of the third next recurrence.)
billing_plan_id	integer	no	Show subscriptions filtered on the billing plan id for fixed schedule recurring subscriptions.
order_day	date	no	Show subscriptions filtered the day of the month the subscription was placed.
is_cancellable	boolean	no	Show subscriptions filtered on whether the subscription is currently cancellable
purchase_date_min	date	no	Show subscriptions filtered on minimum purchase date
purchase_date_max	date	no	Show subscriptions filtered on maximum purchase date
next_ship_date_min	date	no	Show subscriptions filtered on a minimum next ship date
next_ship_date_max	date	no	Show subscriptions filtered on the maximum next ship date
last_ship_date_min	date	no	Show subscriptions filtered on a minimum last ship date
last_ship_date_max	date	no	Show subscriptions filtered on the maximum last ship date
next_active_ship_date_min	date	no	Show subscriptions filtered on the minimum next active ship date
next_active_ship_date_max	date	no	Show subscriptions filtered on the maximum next active ship date
product_id	big int	no	Show subscriptions filtered on the product ID of a line item on the subscription.
page	integer	no	The page of the result to show. (Size 50)

Data Object

Element	Type	Description

Element descriptions pending...

Order Hooks

Reduce Product Quantity Hook

POST /api/third_party/manage/subscription/orders/{order_id}/reduce_product_quantity?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
   "product_internal_id": "644",
   "quantity": "1",
   "order_count": "1"
}

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "message": "OK",
  "data": {
    "id": 500,
    "order_hooks": [
      {
        "title": "reduce_quantity",
        "orders_remaining": 1,
        "quantity": 1,
        "bold_product_id": 644,
        "conditions": [
          {
            "condition_type": "countdown",
            "condition_value": "1"
          }
        ]
      }
    ]
  }
}

This endpoint allows you to apply a hook to a subscription that will reduce the quantity of a product or remove the product if the quantity is reduced below 1. The hook will occur after the number of orders indicated by the order_count in the request. The number of orders required to process with the specific product on the order will be indicated in the response by the condition_value.

POST /api/third_party/manage/subscription/orders/{order_id}/reduce_product_quantity

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Request Body

Element	Type	Description
product_internal_id	integer	Recurring Orders internal product ID for the subscription product receiving the hook.
quantity	integer	The number that will be used to subtract from the subscription product quantity.
order_count	integer	The number of orders that will process before the hook will be applied.

Data Object

Element	Type	Description
id	integer	Subscription Order ID
order_hooks	array	List of Order Hook Object

Delete Order Hooks

DELETE api/third_party/manage/subscription/orders/{order_id}/order_hooks?customer_id={customer_id}&shop={myshopify_domain} HTTP/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Example response has been truncated for brevity

{
  "status": 200,
  "success": true,
  "data": {
    "id": 1
  }
}

This endpoint will delete or remove all pending order hooks on a subscription. Order hooks represent changes that are going to take place to the subscription in the future such as the removal of one time products, dynamic discounts, and the ability to cancel a subscription after a number of orders have passed. If these order hooks are removed, these future changes will not take place, but you will be more freely allowed to edit a subscription.

DELETE api/third_party/manage/subscription/orders/{order_id}/order_hooks

URL Parameters

Element	Type	Description
order_id	integer	Subscription Order ID
customer_id	integer	Shopify Customer ID
shop	string	The store's Shopify domain, e.g. mystore.myshopify.com

Data Object

Element	Type	Description
id	integer	Subscription Order ID

Objects

Build a Box Object

{
  "date": "2018-06-12",
  "status": "See details in Build a Box Statuses table",
  "choices": [
    {
      "slot_id": 1,
      "product_id": 111,
      "variant_id": 222,
      "quantity": 1
    }
  ]
}

Element	Sub Element	Type	Description
date		integer	Build a Box date in Y-m-d format
status		integer	Look on statuses
choices		array	List of BaB choices
	slot_id	integer	Slot ID
	product_id	integer	Shopify Product ID
	variant_id	integer	Shopify variant ID
	quantity	integer	Product Quantity

Build a Box Statuses

Status	Definition
locked	Inside of lock time with choices in database
locked_default_choices	Inside of lock time without choices in database
locked_after_choices_made	Choices made and in available range but lock after choices is turned on in group
available	In available range with no changes in database
available_choices_made	In available range with choices in database
unavailable	Date beyond time to make choices
unavailable_choices_made	Date beyond time to make choices but previously choices were made

Order Discount Object

{
   "discount_code": "DISCOUNTCODE",
   "discount_details": "Free shipping to Anywhere up to $100.00 or less"
   "discount_uses_per_customer": 3,
   "discount_used_by_customer": 2
}

Element	Type	Description
discount_code	string	Discount Code
discount_details	string	Translated details for discount, for example: $10.00 off all orders
discount_uses_per_customer	integer	Number of times the discount code can be used per customer. If value is 0, no limit has been set. Note that this is only included in the Get Initial Data endpoint.
discount_used_by_customer	integer	Number of times the discount code has been used by the customer. If discount_uses_per_customer is set to 0, this elements value will be null. Note that this is only included in the Get Initial Data endpoint.

Order Discount Queue Object

{
  "discount_queue_id": 2,
  "discount_code": "DISCOUNT10",
  "discount_details": "$10.00 off all orders"
}

Element	Type	Description
discount_queue_id	integer	Internal Discount Queue ID
discount_code	string	Discount Code
discount_details	string	Translated details for discount, for example: $10.00 off all orders

Discount Manage Offer Object

{
  "id": 3,
  "offer_type": 2,
  "discount_code_id": null,
  "cancel_reason_id": 1
}

Element	Type	Description
id	integer
offer_type	integer
discount_code_id	integer
cancel_reason_id	integer

Discount Offer Object

{
  "id": 5,
  "type": 2,
  "discount_code": "CANCELCODE",
  "useable_time": 200,
  "only_first_discount": 0,
  "discount_type": 2,
  "discount_amount": "2.00",
  "discount_condition": 0,
  "discount_condition_amount": "0.00",
  "free_shipping_amount": "0.00",
  "free_shipping_country_id": 1,
  "free_shipping_country": "All countries",
  "start_date": "2017-03-24",
  "end_date": "0000-00-00",
  "used": 0,
  "status": 0,
  "deleted": 0,
  "once_per_customer": 0,
  "eligible_product_list": "",
  "id_parent": 0,
  "cancel_id": 1,
  "offer_type": 1,
  "cancel_reason_id": 1
}

Element	Type	Description
id	integer	Unique identifier of the discount code
type	integer	Refers to the discount type, ( 1 = Standard Discount, 2 = Cancellation Discount, 3 = Bulk Group Discount)
discount_code	string	The string code used to identify the discount, and to be entered at checkout or on the manage subscription page
useable_time	integer	The total number of times a discount code can be used
only_first_discount	integer	Whether the discount can be used on checkout only
discount_type	integer	Refers to whether the discount is a fixed or percentage amount. (Fixed = 1, Percentage = 2)
discount_amount	string	The amount that the discount would subtract from the order
discount_condition	integer	Refers to whether the discount will remove the amount from the entire order or chosen products. (0 = entire order, 2 = these products, 3 = not these products)
discount_condition_amount	string	The minimum order total amount for a discount code to be applied
free_shipping_amount	string	If the shipping amount is less than or equal to this value and discount_type is set to 3 then free shipping is applied
free_shipping_country_id	integer	The ids countries that qualify for free shipping
free_shipping_country	string	The countries that qualify for free shipping if discount code is of type 3
start_date	date	The date in CST, that a discount code will become valid
end_date	date	The date in CST, that a discount code will become invalid
used	integer	The total number of times a discount code has been used
status	integer	If equal to 1, then discount code is disabled and pauses the code from being applied to subscriptions that currently have it. If equal to 2 then, discount code is disabled and allows current subscriptions with the code applied to keep getting the discount applied to their orders.
deleted	integer	Refers to is a discount code has been deleted
once_per_customer	integer	Refers to the total number of times a discount code can be used per customer
eligible_product_list	string	The list of products that a discount code either applies to or does not apply to.
id_parent	integer	The id of the parent discount code in the case of bulk group discount codes
cancel_id	integer
offer_type	integer
cancel_reason_id	integer

Order Fixed Recurrences Object

{
  "bold_order_id": 1,
  "total_recurrences": 6,
  "recurrence_count": 1,
  "one_charge_only": 0,
  "recurr_after_limit": 0
}

Element	Type	Description
bold_order_id	integer	Subscription Order ID
total_recurrences	integer	Number of prepaid/limited subscriptions
recurrence_count	integer	Current Orders Shipped
one_charge_only	integer	If order is prepaid: 0 - no, 1 - yes
recurr_after_limit	integer	Automatically renew after last prepaid order Allowed: 0 - no / 1 - yes

General Settings Object

{
  "recurring_type": 2,
  "cancel_mode": 1,
  "provide_cancel_incentives_enabled": false,
  "custom_cancel_message_enabled": false,
  "custom_cancel_message": null,
  "shop_name": "Test Shop",
  "allow_change_shipping_date": true,
  "allow_change_discounts": true,
  "allow_manage_prepaid": false,
  "bold_token": "123",
  "bold_signature": "123",
  "select_products_url": "https://test.myshopify.com/tools/checkout/manage_subscription_box/select_products/",
  "gateway_name": "cashier",
  "gateway_token": "token"
}

Element	Type	Description
recurring_type	integer	1 - 2 -
cancel_mode	string	Cancellation Management mode: cancel_mode_standard cancel_mode_off cancel_mode_custom_reasons cancel_mode_special_instruction
gateway_name	string	Payment gateway name: stripe braintree spreedly cashier
gateway_token	string	Payment gateway token
provide_cancel_incentives_enabled	string
custom_cancel_message_enabled	boolean
custom_cancel_message	string
shop_name	string	Shop name
allow_change_shipping_date	boolean
allow_change_discounts	boolean
allow_manage_prepaid	boolean
bold_token	string	BOLD-Authorization Token
bold_signature	string	BOLD Signature
select_products_url	string	The URL for Select Build A Box products

Order Object

{
	"id": 1,
	"shopify_customer_id": 1,
	"interval_number": 1,
	"interval_type_id": 1,
	"first_name": "FirstName",
	"last_name": "LastName",
	"customer_email": "[email protected]",
	"address1": "Address1",
	"address2": null,
	"country": "Country",
	"province": "Province",
	"city": "City",
	"zip": "Zip",
	"phone": "1111111111",
	"company": "Bold",
	"purchase_date": "2018-06-12",
	"delete_date": null,
	"last_ship_date": "2018-06-12",
	"next_ship_date": "2018-06-12",
	"discount_code_id": 0,
	"cancel_discount_code_id": 0,
	"billing_first_name": "FirstName",
	"billing_last_name": "LastName",
	"billing_address1": "Address1",
	"billing_address2": "Apt 102",
	"billing_country": "Country",
	"billing_province": "Province",
	"billing_city": "City",
	"billing_zip": "Zip",
	"billing_phone": "1111111111",
	"billing_company": "Bold",
	"notes": null,
	"taxes_included": 0,
	"tax_shipping": 0,
	"attributes": "[]",
	"is_cancellable": 1,
	"cancel_reason": null,
	"reactivatable": false,
	"next_active_ship_date": null,
	"billing_plan_id": 0,
	"order_day": null,
	"last_updated": "2018-06-12 11:11:51",
	"order_logs": [
	   {
		  "shopify_order_num": "#1",
		  "shopify_order_token": "1",
		  "price": "1.00",
		  "tax": "1.00",
		  "shipping": "1.00",
		  "purchase_date": "2018-06-12",
		  "share_shipping": false,
		  "discount_amount": "0.00",
		  "free_shipping_discount_applied": 0,
		  "charged_amount": "1.00"
	   }
	],
	"order_product_exceptions": [
	   {
		  "date": "2018-07-12",
		  "products": [
			 {
				"product_internal_id": 1,
				"quantity": 8
			 }
		  ]
	   }
	],
	"order_interval_type": {
	   "interval_type": "day",
	   "interval_text": "Day",
	   "estimated_days": 1
	},
	"order_fixed_recurrences": null,
	"order_products": [
	   {
		  "id": 1,
		  "shop_app_id": 1,
		  "bold_order_id": 1,
		  "product_id": 111,
		  "variant_id": 222,
		  "price": "1.00",
		  "quantity": 1,
		  "gram": 0,
		  "product_title": "ProductTitle",
		  "variant_title": "VariantTitle",
		  "status": 0,
		  "price_changed": 0,
		  "shopify_price": "1.00",
		  "shopify_new_price": null,
		  "sku": "",
		  "shopify_inventory": null,
		  "inventory_management": null,
		  "taxable": 1,
		  "properties": "{\u0022frequency_num\u0022:\u00227\u0022,\u0022frequency_type\u0022:\u00221\u0022,\u0022group_id\u0022:\u00226\u0022,\u0022is_prepaid\u0022:\u0022\u0022,\u0022total_recurrences\u0022:\u0022\u0022,\u0022prepaid_id\u0022:\u0022\u0022,\u0022recurr_after_limit\u0022:\u00221\u0022,\u0022_ro_subscription_box_choices\u0022:[{\u0022slot\u0022:\u002211\u0022,\u0022quantity\u0022:\u00222\u0022},{\u0022slot\u0022:\u002212\u0022,\u0022quantity\u0022:\u00221\u0022}],\u0022_ro_billing_plan\u0022:0,\u0022frequency_type_text\u0022:\u0022Day(s)\u0022}",
		  "vendor": "VendorName",
		  "is_active": true,
		  "last_updated": "2018-06-12 11:06:23",
		  "properties_group_id": 6
	   }
	],
	"order_shipping_rate": {
	   "bold_order_id": 1,
	   "code": "DOM.EP",
	   "name": "ShipName",
	   "price": 1.00,
	   "source": "shopify",
	   "need_change": false,
	   "hash": "123"
	},
	"order_exceptions":[
	   "2018-08-12",
	   "2018-09-12"
	],
	"order_hooks": [
	   {
		  "bold_product_id": 111,
		  "conditions": [
			 {
				"condition_type": "countdown",
				"condition_value": "8"
			 }
		  ],
		  "title": "Switch Price",
		  "new_price": null
	   }
	],
	"next_orders": ["2018-06-12",...],
	"is_billing_the_same": true,
	"build_a_box_next_orders": [
	   {
		  "date": "2018-06-12",
		  "status": "See details in Build a Box Statuses table",
		  "choices": [
			 {
				"slot_id": 1,
				"product_id": 111,
				"variant_id": 222,
				"quantity": 1
			 },{...},{...}],
	   },{...},{...}],
	"build_a_box": true,
	"has_prepaid": false,
	"group_id": 1,
	"discount": null,
	"discount_queue": [
	],
	"credit_card": {
	   "last_four": "1111",
	   "expiry_date": "2021-12-31 00:00:00"
	}
 }

Element	Type	Description
id	integer	Recurring Orders internal product ID
shopify_customer_id	integer	Shopify Customer ID
interval_number	integer	Recurring interval number for example: 2 (for every 2 weeks/days etc.)
interval_type_id	integer	Recurring interval type: 1 - Day 2 - Week 3 - Month 5 - Year
first_name	string	Shipping First Name
last_name	string	Shipping Last name
customer_email	string	Customer Email address
address1	string	Shipping Address
address2	string	Shipping Address optional
country	string	Shipping Country
province	string	Shipping Province
city	string	Shipping City
zip	string	Shipping Zip Code
phone	string	Shipping Phone Number
company	string	Shipping Company
purchase_date	date	First order date
delete_date	date	Delete date or null
last_ship_date	date	Last order date
next_ship_date	date	next order date
discount_code_id	integer	Discount Code ID
cancel_discount_code_id	integer	Cancellation Code ID
billing_first_name	string	Billing First Name
billing_last_name	string	Billing Last name
billing_address1	string	Billing Address
billing_address2	string	Billing Address optional
billing_country	string	Billing Country
billing_province	string	Billing Province
billing_city	string	Billing City
billing_zip	string	Billing Zip Code
billing_phone	string	Billing Phone Number
billing_company	string	Billing Company
notes	string	Order notes
taxes_included	integer
tax_shipping	integer
attributes	string
is_cancellable	integer
cancel_reason	string
reactivatable	integer	0/1
next_active_ship_date	date
billing_plan_id	integer
order_day	integer
last_updated	datetime
order_logs	array	List of Order Log Objects
order_product_exceptions	array	List of Order Product Exceptions Object
order_interval_type	array
order_fixed_recurrences	object/null	Order Fixed Recurrences Object
order_products	array	List of Order Product Object
order_shipping_rate	object	Order Shipping Object
order_exceptions	array	Array of order exception dates
order_hooks	array	Order hooks Object
next_orders	array	Array of next order dates
is_billing_the_same	boolean	true/false
build_a_box_next_orders	array	Build A Box Object
build_a_box	boolean	If order is Build a Box type
has_prepaid	boolean	If order is prepaid
group_id	integer	Subscription Group ID
discount	object / null	Order Discount Object
discount_queue	array	List of Order Discount Queue Objects
credit_card	array

##Order Log Object

{
  "shopify_order_num": "#1",
  "shopify_order_token": "1",
  "price": "1.00",
  "tax": "1.00",
  "shipping": "1.00",
  "purchase_date": "2018-06-12",
  "share_shipping": false,
  "discount_amount": "0.00",
  "free_shipping_discount_applied": 0,
  "charged_amount": "1.00"
}

Element	Type	Description
shopify_order_num	string	Shopify order Number
shopify_order_token	string
price	string	Order Price value
tax	string	Order Tax value
shipping	string	Order Shipping value
purchase_date	date	Purchase date
share_shipping	boolean	Is shipping is shared
discount_amount	string	Discount amount
free_shipping_discount_applied	integer
charged_amount	string	Charged amount

Order Hook Object

{
  "title": "reduce_quantity",
  "bold_product_id": 644,
  "quantity": 1,
  "orders_remaining": 1,
  "conditions": [
    {
      "condition_type": "countdown",
      "condition_value": "1"
    }
  ]
}

{
  "title": "switch_price",
  "bold_product_id": 644,
  "price": 3.0,
  "orders_remaining": 1,
  "conditions": [
    {
      "condition_type": "countdown",
      "condition_value": "1"
    }
  ]
}

{
  "title": "switch_product",
  "bold_product_id": 644,
  "price": 3.0,
  "product_id": 23456432,
  "variant_id": 34456634,
  "orders_remaining": 1,
  "conditions": [
    {
      "condition_type": "countdown",
      "condition_value": "1"
    }
  ]
}

{
    "title": "make_cancellable",
    "bold_product_id": NULL,
    "orders_remaining": 1,
    "conditions": [{
        "condition_type": "order_countdown",
        "condition_value": "1"
    }]
}

Element	Sub Element	Type	Description
title		string	Type of hook
bold_product_id*		integer	Indicates the id from the Order Product Object that the hook will be applied to. Only used for product based hooks which have a condition type of countdown.
conditions
	condition_type	string	The condition type countdown indicates the hook is monitoring the number of orders where a specific product exists. The condition type order_countdown indicates the hook is monitoring the number of orders that have processed for the subscription.
	condition_value	string	Indicates the amount of orders that need to process before the hook is applied.
quantity*		integer	Indicates the quantity that a product will be reduced by after the number of orders has passed.
price*		decimal	Indicates the price the product will be changed to after the number of orders has passed.
product_id*		integer	Indicates the Shopify product_id of the product that will replace the existing product after the number of orders has passed.
variant_id*		integer	Indicates the Shopify variant_id of the product that will replace the existing product after the number of orders has passed.
orders_remaining		integer	Indicates the number of orders remaining before the hook is applied to the order.

*These attributes are dependant on the hook type

Hook	Attribute	Condition Type
reduce_quantity		countdown	Reduce Product Quantity Hook
	bold_product_id
	quantity
switch_price		countdown
	bold_product_id
	price
switch_product		countdown
	bold_product_id
	product_id (Shopify)
	product_id (Shopify)
make_cancellable		order_countdown

Order Product Object

{
   "id": 5,
   "shop_app_id": 1,
   "bold_order_id": 1,
   "product_id": 111,
   "variant_id": 222,
   "price": "10.00",
   "quantity": 1,
   "gram": 100,
   "product_title": "ProductTitle",
   "variant_title": "VariantTItle",
   "status": 0,
   "price_changed": 0,
   "shopify_price": "10.00",
   "shopify_new_price": null,
   "sku": "skuprod1",
   "shopify_inventory": null,
   "inventory_management": "shopify",
   "taxable": 1,
   "properties": "{\u0022frequency_num\u0022:1,\u0022frequency_type\u0022:2,\u0022frequency_type_text\u0022:\u0022Weekx(s***)\u0022,\u0022group_id\u0022:\u00221\u0022,\u0022is_prepaid\u0022:\u0022\u0022,\u0022total_recurrences\u0022:\u0022\u0022,\u0022prepaid_id\u0022:\u0022\u0022,\u0022recurr_after_limit\u0022:\u00220\u0022,\u0022_ro_billing_plan\u0022:0}",
   "vendor": "Vendor",
   "is_active": true,
   "shopify_product": {
      "id": 111,
      "body_html": "",
      "handle": "product_handle",
      "product_type": "",
      "published_scope": "global",
      "title": "ProductTitle",
      "vendor": "vendor",
      "tags": "",
      "options": [
         {
            "id": 123,
            "name": "Title",
            "position": 1,
            "product_id": 111,
            "values": [
               {
                  "Default Title"
               }
            ]
         }
      ],
      "images":{...},
      "created_at": "2017-02-28T09:41:56+10:30",
      "updated_at": "2017-06-16T02:12:55+09:30",
      "published_at": "2017-02-28T09:35:00+10:30",
      "image": {...},
      "variant": {...}
   }
}

Element	Type	Description
id	integer	Recurring Orders internal product ID
shop_app_id	integer	Shop App ID
bold_order_id	integer	Subscription Order ID
product_id	integer	Shopify product ID
variant_id	integer	Shopify variant ID
price	string	Product Price
quantity	integer	Product quantity
gram	integer	Gram
product_title	string	Product title
variant_title	string	Product variant
status	integer	0 - active, 1 - inactive
price_changed	integer
shopify_price	string	Shopify price
shopify_new_price	string
sku	string	SKU
shopify_inventory	string	Shopify inventory
inventory_management	string	Shopify Inventory Management
taxable	integer	If product is taxable
properties	string	Recurring Orders properties
vendor	string	Vendor name
is_active	integer	0/1
shopify_product	object	Shopify Product Object

Order Product Exceptions Object

{
  "date": "2017-06-01",
  "products": [
    {
      "product_internal_id": 1,
      "quantity": 1
    },
    {
      "product_internal_id": 2,
      "quantity": 1
    },
    {
      "product_internal_id": 3,
      "quantity": 0
    }
  ]
}

Element	Sub Element	Type	Description
date		integer	product exception date in Y-m-d format
products
	product_internal_id	integer	Recurring Orders internal product ID
	quantity	integer	Product Quantity

Order Shipping Rate Object

{
  "bold_order_id": 1,
  "code": "DOM.EP",
  "name": "Expedited Parcel",
  "price": "10.00",
  "source": "canada_post",
  "need_change": false,
  "hash": "hash_value"
}

Element	Type	Description
bold_order_id	integer	Subscription Order ID
code	string	Order Shipping Code
name	string	Order Shipping Name
price	string	Shipping Price
source	string	Shipping Source for example: shopify, cashier, decimal etc.
need_change	integer	0/1
hash	string	shipping Hash

Initial Data Order Object

{
	"id": 1,
	"shopify_customer_id": 1,
	"interval_number": 1,
	"interval_type_id": 1,
	"first_name": "FirstName",
	"last_name": "LastName",
	"customer_email": "[email protected]",
	"address1": "Address1",
	"address2": null,
	"country": "Country",
	"province": "Province",
	"city": "City",
	"zip": "Zip",
	"phone": "1111111111",
	"company": "Bold",
	"purchase_date": "2018-06-12",
	"delete_date": null,
	"last_ship_date": "2018-06-12",
	"next_ship_date": "2018-06-12",
	"discount_code_id": 0,
	"cancel_discount_code_id": 0,
	"billing_first_name": "FirstName",
	"billing_last_name": "LastName",
	"billing_address1": "Address1",
	"billing_address2": "Apt 102",
	"billing_country": "Country",
	"billing_province": "Province",
	"billing_city": "City",
	"billing_zip": "Zip",
	"billing_phone": "1111111111",
	"billing_company": "Bold",
	"notes": null,
	"taxes_included": 0,
	"tax_shipping": 0,
	"attributes": "[]",
	"is_cancellable": 1,
	"cancel_reason": null,
	"reactivatable": false,
	"next_active_ship_date": null,
	"billing_plan_id": 0,
	"order_day": null,
	"last_updated": "2018-06-12 11:11:51",
	"order_logs": [
	   {
		  "shopify_order_num": "#1",
		  "shopify_order_token": "1",
		  "price": "1.00",
		  "tax": "1.00",
		  "shipping": "1.00",
		  "purchase_date": "2018-06-12",
		  "share_shipping": false,
		  "discount_amount": "0.00",
		  "free_shipping_discount_applied": 0,
		  "charged_amount": "1.00"
	   }
	],
	"order_product_exceptions": [
	   {
		  "date": "2018-07-12",
		  "products": [
			 {
				"product_internal_id": 1,
				"quantity": 8
			 }
		  ]
	   }
	],
	"order_interval_type": {
	   "interval_type": "day",
	   "interval_text": "Day",
	   "estimated_days": 1
	},
	"order_fixed_recurrences": null,
	"order_products": [
	   {
		  "id": 1,
		  "shop_app_id": 1,
		  "bold_order_id": 1,
		  "product_id": 111,
		  "variant_id": 222,
		  "price": "1.00",
		  "quantity": 1,
		  "gram": 0,
		  "product_title": "ProductTitle",
		  "variant_title": "VariantTitle",
		  "status": 0,
		  "price_changed": 0,
		  "shopify_price": "1.00",
		  "shopify_new_price": null,
		  "sku": "",
		  "shopify_inventory": null,
		  "inventory_management": null,
		  "taxable": 1,
		  "properties": "{\u0022frequency_num\u0022:\u00227\u0022,\u0022frequency_type\u0022:\u00221\u0022,\u0022group_id\u0022:\u00226\u0022,\u0022is_prepaid\u0022:\u0022\u0022,\u0022total_recurrences\u0022:\u0022\u0022,\u0022prepaid_id\u0022:\u0022\u0022,\u0022recurr_after_limit\u0022:\u00221\u0022,\u0022_ro_subscription_box_choices\u0022:[{\u0022slot\u0022:\u002211\u0022,\u0022quantity\u0022:\u00222\u0022},{\u0022slot\u0022:\u002212\u0022,\u0022quantity\u0022:\u00221\u0022}],\u0022_ro_billing_plan\u0022:0,\u0022frequency_type_text\u0022:\u0022Day(s)\u0022}",
		  "vendor": "VendorName",
		  "is_active": true,
		  "last_updated": "2018-06-12 11:06:23",
		  "properties_group_id": 6
	   }
	],
	"order_shipping_rate": {
	   "bold_order_id": 1,
	   "code": "DOM.EP",
	   "name": "ShipName",
	   "price": 1.00,
	   "source": "shopify",
	   "need_change": false,
	   "hash": "123"
	},
	"order_exceptions":[
	   "2018-08-12",
	   "2018-09-12"
	],
	"order_hooks": [
	   {
		  "bold_product_id": 111,
		  "conditions": [
			 {
				"condition_type": "countdown",
				"condition_value": "8"
			 }
		  ],
		  "title": "Switch Price",
		  "new_price": null
	   }
	],
	"next_orders": ["2018-06-12",...],
	"is_billing_the_same": true,
	"build_a_box_next_orders": [
	   {
		  "date": "2018-06-12",
		  "status": "See details in Build a Box Statuses table",
		  "choices": [
			 {
				"slot_id": 1,
				"product_id": 111,
				"variant_id": 222,
				"quantity": 1
			 },{...},{...}],
	   },{...},{...}
	],
	"build_a_box": true,
	"has_prepaid": false,
	"group_id": 1,
	"discount": null,
	"discount_queue": [
	],
	"credit_card": {
	   "last_four": "1111",
	   "expiry_date": "2021-12-31 00:00:00"
	},
	"status": 0
 }

Element	Type	Description
id	integer	Recurring Orders internal product ID
shopify_customer_id	integer	Shopify Customer ID
interval_number	integer	Recurring interval number for example: 2 (for every 2 weeks/days etc.)
interval_type_id	integer	Recurring interval type: 1 - Day 2 - Week 3 - Month 5 - Year
first_name	string	Shipping First Name
last_name	string	Shipping Last name
customer_email	string	Customer Email address
address1	string	Shipping Address
address2	string	Shipping Address optional
country	string	Shipping Country
province	string	Shipping Province
city	string	Shipping City
zip	string	Shipping Zip Code
phone	string	Shipping Phone Number
company	string	Shipping Company
purchase_date	date	First order date
delete_date	date	Delete date or null
last_ship_date	date	Last order date
next_ship_date	date	next order date
discount_code_id	integer	Discount Code ID
cancel_discount_code_id	integer	Cancellation Code ID
billing_first_name	string	Billing First Name
billing_last_name	string	Billing Last name
billing_address1	string	Billing Address
billing_address2	string	Billing Address optional
billing_country	string	Billing Country
billing_province	string	Billing Province
billing_city	string	Billing City
billing_zip	string	Billing Zip Code
billing_phone	string	Billing Phone Number
billing_company	string	Billing Company
notes	string	Order notes
taxes_included	integer
tax_shipping	integer
attributes	string
is_cancellable	integer
cancel_reason	string
reactivatable	integer	0/1
next_active_ship_date	date
billing_plan_id	integer
order_day	integer
last_updated	datetime
order_logs	array	List of Order Log Objects
order_product_exceptions	array	List of Order Product Exceptions Object
order_interval_type	array
order_fixed_recurrences	object/null	Order Fixed Recurrences Object
order_products	array	List of Order Product Object
order_shipping_rate	object	Order Shipping Object
order_exceptions	array	Array of order exception dates
order_hooks	array	Order hooks Object
next_orders	array	Array of next order dates
is_billing_the_same	boolean	true/false
build_a_box_next_orders	array	Build A Box Object
build_a_box	boolean	If order is Build a Box type
has_prepaid	boolean	If order is prepaid
group_id	integer	Subscription Group ID
discount	object / null	Order Discount Object
discount_queue	array	List of Order Discount Queue Objects
credit_card	array
status	integer	Order payment status: 0 - no failed tx's 1 - failed tx's 2 - authentication required

How-to Guides

Get Shipping Rates

You can use the Shipping Rates endpoint to get the shipping rates that the subscription currently qualifies for, or the shipping rates the subscription would qualify for if a change to the subscription was made.

Getting Available Shipping Rates for a Subscription

To get all of the available shipping rates that a subscription currently qualifies for, make a GET request to the Shipping Rates endpoint with the subscription id. (Order id)

GET api/third_party/manage/subscription/orders/{order_id}/shipping_rates?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Get Shipping Rates for Shipping Address Changes

When you are going to change the shipping address associated with a subscription, you may qualify for different shipping rates.

To get the available rates you will send the new shipping address in the URL parameters of the request.

GET api/third_party/manage/subscription/orders/2478/shipping_rates?zip={shipping_zip}&country={shipping_country}&city={shipping_city}&province={shipping_province}&address1={shipping_address_1}&address2={shipping_address2}=&phone={phone}&customer_id={shopify_customer_id}&t=1575060452553 HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Getting Shipping Rates for Product Quantity Changes

When you are going to change the quantity of a product on a subscription, you may qualify for different shipping rates. This is because the total price or weight of the subscription may change if you change the quantity.

To get the available shipping rates, with a product quantity changed you will send a URL encoded array of the products and the new quantities.

[
  {
    "product_internal_id": 2542,
    "quantity": "2",
    "is_deleted": false
  }
]

product_internal_id: The bold product id quantity: The new quantity that you want to change it to is_deleted: This is used if you are setting the quantity to 0. If set to true, will delete the product from the subscription

GET api/third_party/manage/subscription/orders/2478/shipping_rates?zip={shipping_zip}&country={shipping_country}&city={shipping_city}&province={shipping_province}&order_products={url_encoded_product_quantity}&customer_id={shopify_customer_id}t=1575056879485 HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Getting Shipping Rates when Adding a Product

When you are going to add a product on a subscription, you may qualify for different shipping rates. This is because the total price or weight of the subscription may change if you add a product.

To get the available shipping rates, when adding a product you will send a URL encoded array of the products you are adding, and their quantities.

[
  {
    "shopify_product_id": 164932858,
    "shopify_variant_id": 1608966106,
    "quantity": 1
  }
]

shopify_product_id: The Shopify product id you are adding to the subscription shopify_variant_id: The Shopify variant id you are adding to the subscription quantity: The quantity of the products you are adding to the subscription

GET api/third_party/manage/subscription/orders/2463/shipping_rates?zip={shipping_zip}&country={shipping_country}&city={shipping_city}&province={shipping_province}&new_order_products={url_encoded_new_products}&customer_id={shopify_customer_id}&t=1571328584531 HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Getting Shipping Rates when Swapping a Product

When you are going to swap a product on a subscription, you may qualify for different shipping rates. This is because the total price or weight of the subscription may change if you swap a product.

To get the available shipping rates, for a product swap you will send the Shopify product id an variant id of the product you are swapping to.

GET api/third_party/manage/subscription/orders/2478/shipping_rates?zip={shipping_zip}&country={shipping_country}&city={shipping_city}&province={shipping_province}&product_internal_id={bold_product_id}&product_id={new_shopify_producut_id}&variant_id={new_shopify_variant_id}&customer_id={shopify_customer_id}&t=1575059258150 HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Swap a Product

In the settings for a subscription group there is an option to allow swapping of products. This allows customers to switch the product they are subscribed to with another product in the subscription group. This can be achieved through the Integrations API.

Step 1: Obtain Your Bearer Token

The Third Party or Integrations API uses a Bearer Authentication scheme. You must make a basic authentication request with your Private API Key and App Handle to receive a bearer token to use with all subsequent API requests.

Generate an API Key

In the Bold Subscriptions Admin navigate to Integrations > API Keys.

Here you can create a new API key. The handle is a way to keep track of where you are using each of the API keys you have generated. Note you must be on the Advanced Price Plan to be able to generate API keys.

Generate Your Token

You will need to create a single request to the authentication endpoint. Read more about authentication The token you receive in response will be valid for 24 hours.

GET api/auth/third_party_token?shop={myshopifyDomain}&handle={appHandle} HTTPS/1.1
Content-Type: application/json
BOLD-Authorization: {privateApiKey}

HTTPS/1.1 200 OK

Step 2: Get Customer Subscription Information

You will need to get information about the customers and subscription to be able to swap the product.

group_id : The id of the subscription group that the subscribed to product belongs to

product_internal_id : The Bold product id of the subscribed to product

To get this information we will make a GET request call to the Subscriptions endpoint.

GET /api/third_party/subscriptions?shop={myshopifyDomain}&shopify_customer_id={shopify_customer_id}7&id={bold_order_id} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

The product_internal_id is subscriptions->order_products->id The group_id is found subscriptions->order_products->properties->group_id

note

You can find the subscription id or bold order id in the Bold Subscriptions Admin under Subscriptions > Customers > Edit > ID

Step 3: Get Swappable Products

You can swap a product with any other product in the same subscription group. You will make a GET request to Group endpoint.

GET /api/third_party/manage/subscription/groups/{group_id}/swap_information?product_internal_id={product_internal_id}&order_id={order_id}&customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

Step 4: Get Available Shipping Rates

When swapping a product, you will need to update the shipping rate for the subscription. In the Shipping Rate object you will see a unique hash. This hash changes depending on the products in the subscription. Because of this even if you are going to keep the same shipping rate, you will need to resend the rate because the hash will have changed.

You will send a GET request to the Shipping Rates endpoint. In the GET request we will include how we are hoping to change the order (i.e. with a product swapped)

GET api/third_party/manage/subscription/orders/2477/shipping_rates?zip={zip_code}&country={shipping_country}&city={shipping_city}&province={shipping_province}&product_id={new_shopify_product_id}&variant_id={new_shopify_variant_id}&customer_id=97235533851&t=1574784594893&shop={myshopify_domain}
BOLD-Authorization: Bearer {token}
Content-Type: application/json

HTTPS/1.1 200 OK

If you are swapping from Product A to Product B then the product_internal_id is Bold product id of Product A product_id and variant_id are the Shopify product and variant ids of Product B.

Step 5: Saving the New Product

Now you have all the information we need to swap the old product with the new product on the subscription. We will send a PUT request to the Swap Product endpoint. You need to send the new product information as well as one of the valid shipping rates we receive in the previous request.

PUT /third_party/manage/subscription/orders/{order_id}/save_swap_product?customer_id={customer_id}&shop={myshopify_domain} HTTPS/1.1
BOLD-Authorization: Bearer {token}
Content-Type: application/json

{
    "order_id": 1,
    "product_internal_id": 1,
    "product_id": 123456789,
    "variant_id": 234567891,
   "order_shipping_rate": {
      "code": "DOM.EP",
      "name": "Expedited Parcel",
      "source": "canada_post",
      "price": "2312.10",
      "need_change": false,
      "hash": "ajk20934joskefj098234kj3ok2o9sudkjasd"
   }
}

HTTPS/1.1 200 OK

When you view the subscription now, you should see the new product. You should also be able to see in the customer's history that the item was swapped.