Customers to Orders, Subscriptions

Let's say we wanted to gather order and subscription information about a given Cratejoy customer.

For these purposes, let's presume that the customer has placed at least one subscription order.

Subscriptions

A customer may have many subscriptions. Within a single subscription, a subscription will have just one of each of the following.

• Product. Here, we could find what subscription product the customer is subscribed to, including product name, product ID, description, etc.

• Product Instance. Here, we can see what instance is associated with the subscription. This is useful if a subscription product contains multiple variants, as each possible combination of variants has a unique product_instance_id. Note that this means products have a one-to-many relationship with product instances.

• Billing. Billing contains information about the subscription product's billing cycle. E.g. billing.rebill_day for a given subscription ID would tell you on what day a monthly subscription is billed.

• Subscription Term. Term indicates what prepay or month-to-month term is associated with the subscription. E.g. for a 3-month prepay subscription, we'd see term.num_cycles as 3.

Note that these capture the subscription's current properties -- a customer changing from a month-to-month term to a 3-month prepay would alter the Term property associated with that subscription ID.

All of these resources (product, product instance, billing, and subscription term) are available as related resources when getting information about a given subscription ID via the Merchant API.

Orders

A single customer may have many orders, and subscriptions and orders can be many-to-many. For example:

• Subscription to Order, One-to-Many: A subscription that has renewed twice, for example, will have 3 orders associated with it: the primary order (order.is_renewal=false) and two renewal orders (order.is_renewal=true).

• Subscription to Order, Many-to-One: An order in which a customer has purchased two different subscriptions.

• Subscription to Order, Many-to-Many: The combination of the above cases!
  A customer places an initial order (order 01) with two subscriptions (Sub A and Sub B) and then later both of those subscriptions renew -- producing order 02 that maps to Sub A and order 03 that maps to Sub B.

Transactions

An order can have many transactions. If a customer tries to pay for an order with an expired card, then successfully pays with a new card, then later has part of the order refunded, we would see three transactions associated with the order (failed, captured, refunded).

Shipments

A shipment can have one-to-one or a many-to-one relationship with orders.

Shipment to Order, One-to-One examples include:

• A standard ecommerce purchase: A customer purchases a single ecommerce product. One order created, with exactly one shipment created.

• A simple monthly subscription purchase. A customer purchases a month-to-month subscription product. One order is created (renewal or not), with one shipment created that maps to one month's subscription box.

Shipments to Order, Many-to-One examples include:

• An order that contains both ecommerce and subscription products if the merchant does not have the Cratejoy Add-Ons app installed. A customer purchases a monthly subscription box and one ecommerce product. This one order would create two separate shipments, one for the subscription product and one for the ecommerce product.

• An order with multiple subscriptions. A customer purchases two monthly subscriptions. This one order would create two separate shipments, one for each subscription.

• An order for a multi-month product. A customer purchases a three-month prepay for a monthly subscription product -- say the subscription product is set to ship for this customer in January, February, and March. This one order would create three shipments of the subscription product, with adjusted_ordered_at dates set for January, February, and March.