NAV Navbar
json
  • Introduction
  • Using Webhooks
  • Webhook Events
  • Using Our API
  • Manage Subscription
  • Subscription Groups
  • Subscriptions
  • Order Hooks
  • Objects
  • How-to Guides
  • 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 Commerce 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)

    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 "" in place of the corresponding event name.

    Subscription Created

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 1,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

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

    Event Name Triggers
    subscription.created
    • Successful checkout

    Subscription Ended

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 0,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    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

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 0,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    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

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 1,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    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

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 1,
                "is_paused": 1,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    A subscription was paused indefinitely.

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

    Subscription Resumed

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 1,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    A paused subscription was resumed.

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

    Subscription Exceptions Removed

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 1,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    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

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "subscription": {
                "id": 12345,
                "shopify_customer_id": 61411983364,
                "interval_number": 1,
                "interval_type_id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "customer_email": "example@gmail.com",
                "address1": "50 Fultz Blvd.",
                "address2": null,
                "country": "Canada",
                "province": "Manitoba",
                "city": "Winnipeg",
                "zip": "R3Y 0L6",
                "phone": null,
                "company": "",
                "purchase_date": "2019-03-27",
                "last_ship_date": "2019-03-27",
                "next_ship_date": "2019-04-27",
                "active": 1,
                "is_paused": 0,
                "discount_code_id": 0,
                "cancel_discount_code_id": 0,
                "billing_first_name": "John",
                "billing_last_name": "Doe",
                "billing_address1": "50 Fultz Blvd.",
                "billing_address2": null,
                "billing_country": "Canada",
                "billing_province": "Manitoba",
                "billing_city": "Winnipeg",
                "billing_zip": "R3Y 0L6",
                "billing_phone": null,
                "billing_company": "",
                "notes": null,
                "taxes_included": 0,
                "tax_shipping": 0,
                "attributes": "{\"Gift Note\": \"Happy Birthday\"}",
                "is_cancellable": 1,
                "cancel_reason": "No reason",
                "reactivatable": 1,
                "next_active_ship_date": "2019-04-27",
                "billing_plan_id": 0,
                "order_day": null,
                "last_updated": "2019-03-27 11:23:51",
                "shopify_order_tags": null,
                "currency": "CAD",
                "currency_exchange_rate": "1.000000000000",
                "currency_format": "$ {{amount}}"
            },
            "shop": { ... }
        }
    }
    

    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

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "order": {
                "subtotal": 15.00,
                "total": 20.00,
                "tax": 2.50,
                "shipping": 2.50,
                "transaction_date": "2019-03-27"
            },
            "subscription": { ... },
            "shop": { ... }
        }
    }
    

    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

    {
        "event_type": "<event.name>",
        "event_time": "2019-03-27 11:24:51",
        "data": {
            "order": {
                "subtotal": 15.00,
                "total": 20.00,
                "tax": 2.50,
                "shipping": 2.50,
                "transaction_date": "2019-03-27"
            },
            "subscription": { ... },
            "shop": { ... }
        }
    }
    

    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

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

    An upcoming order was sheduled to be skipped.

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

    Order Resumed

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

    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/{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"
    }
    

    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.

    Manage Subscription Endpoints

    GET /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",
       }
    }
    

    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)

    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": "graydon@boldapps.net",
                ...
            },
            ...
    }
    
    

    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.

    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, }, { "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
    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 a 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

    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

    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

    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

    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": "customer@email.com",
                "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": 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,
                      "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": [
    ], "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

    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

    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

    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

    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

    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

    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

    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

    Data Object

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

    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

    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

    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": "marie.curie@boldcommerce.com",
                    "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

    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

    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

    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

    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
    order_id integer Subscription Order ID
    customer_id integer Shopify Customer ID

    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

    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

    Request Body

    Element Type Description
    next_ship_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

    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

    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

    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

    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

    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

    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

    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": [
                    {
                        "id": 2,
                        "group_id": 1,
                        "shop_app_id": 2,
                        "variant_id": 8291055108151,
                        "last_batch_id": 59
                    },
                    {
                        "id": 3,
                        "group_id": 1,
                        "shop_app_id": 3,
                        "variant_id": 8291055108151,
                        "last_batch_id": 67
                    }
                ],
                "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
    myshopifyDomain string The logged in store's Myshopify Domain, e.g. dudestore.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": "donnie@testdomain.net",
                "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",
                "last_ship_date": "2018-06-28",
                "next_ship_date": "2018-06-29",
                "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,
                "taxes_included": 0,
                "tax_shipping": 0,
                "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",
                "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 logged in store's Myshopify Domain, e.g. dudestore.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
    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 Shopify domain name

    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

    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"
    }
    
    Element Type Description
    discount_code string Discount Code
    discount_details string Translated details for discount, for example: $10.00 off all orders

    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
    type integer
    discount_code string
    useable_time integer
    only_first_discount integer
    discount_type integer
    discount_amount string
    discount_condition integer
    discount_condition_amount string
    free_shipping_amount string
    free_shipping_country_id integer
    free_shipping_country string
    start_date date
    end_date date
    used integer
    status integer
    deleted integer
    once_per_customer integer
    eligible_product_list string
    id_parent integer
    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": "customer@email.com",
        "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.00,
        "orders_remaining": 1,
        "conditions": [{
            "condition_type": "countdown",
            "condition_value": "1"
        }]
    }
    
    {
        "title": "switch_product",
        "bold_product_id": 644,
        "price": 3.00,
        "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": "customer@email.com",
        "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/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/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/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/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 api key

    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_interal_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

    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_produduct_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.