Skip to main content Link Search Menu Expand Document (external link)

Using the API

This page contains helpful information for developers trying to use the Ongoing Subscriptions API to power their custom integration.

You will find more information about:

  • How are orders and subscriptions created?
  • How do billing attempts work?
  • How are line items determined for an Order and for a Subscription?
  • What data types are available through the Ongoing Rest API?
  • A list of the unique identifiers available

Table of Contents

Definitions

  • Order: Any orders listed in the Ongoing Subscriptions API will be related to a specific Subscription.
  • Subscription: Sometimes also referred to as ‘SubscriptionContract’. Can contain one Order or many Orders.
  • Customer: The person who has ordered a Subscription.
  • Line Item: A product that is associated with an Order or a Subscription.
  • Billing Attempts: After the first order, Billing Attempts will be scheduled on all Active Subscription. A successful Billing Attempt will created new Orders that are related to the Subscription.

Creation of Orders and Subscriptions

First Order and New Subscription

When a Customer purchases an Order if there are any Line Items that will be reordered there will be a Subscription created. Based on the Plan.

Follow up Orders for a Subscription are created when there is a successful Billing Attempt.

Billing Attempts create additional Orders

Billing Attempts are scheduled based on the Delivery and Billing frequency for a Subscription.

Imagine a monthly Subscription has been created by a new Order placed on January 1st.

The next Billing Attempt will be scheduled on February 1st.

  • If the Billing Attempt is successful a new Order will be created. This Order will be associated with the Subscription
  • If the Billing Attempt is not successful, no Order will be created.

Line Items

Order Line Items

The Order can contain at least one Line Item.

Ongoing Subscriptions does not modify any aspect of an Order.

Due to this reason Line Items for an Order will never change as a result of Ongoing Subscriptions. However, another app or modifications to the order through another means can can remove a line item from an Order.

Subscription Line Items

The Subscription will always contain at least one Line Item.

A Subscription can have many aspects modified including Line Items.

The Line Item for an Order will be determined by the Subscription when the Order is first created.

Example:

Imagine that we have a new monthly Subscription created on January 1st with 1 line item:

  • 1lb. Coffee

Subscription Order #1 will contain the line items:

  • 1lb. Coffee

Now imagine we add a new line item to the Subscripton on January 15th (before the scheduled billing date):

  • 1 month supply coffee filters

Order #2 will contain two line items:

  • 1lb. Coffee
  • 1 month supply coffee filters

While Order #1 will stil only contain

  • 1lb. Coffee

Available Data via the Rest API

Unique Identifiers

There are two unique identifiers in the Ongoing Subscriptions API

  • shopifyId - The unique id based on the id in Shopify. This id will never change.
  • uuid - The unique id used only within Ongoing

shopifyId

All data that can be accessed via the standard Shopify API will have a shopifyId

Example

"orders": [
    {
      "shopifyId": "gid://shopify/Order/1234567890",
      ...
    }
]

uuid

If the data can be accessed directly via the Ongoing Subscriptions API then it will also contain a uuid. This uuid is unique to the type of data it relates to.

Example

"subscriptions": [
    {
      "uuid": "a9dd6766-9dd8-11ec-88cc-0242ac130003",
      ...
    }
]