{"_id":"5907695b6a3ed52f00b94fea","category":{"_id":"590768e54669da0f00db5c0b","__v":0,"version":"58112e71ded0340f0085d02a","project":"551e85be610f400d00837db7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-01T16:57:09.494Z","from_sync":false,"order":6,"slug":"relationships","title":"Merchant API Relationships"},"project":"551e85be610f400d00837db7","user":"58a36246b2c9e91b00e551cb","__v":0,"version":{"_id":"58112e71ded0340f0085d02a","project":"551e85be610f400d00837db7","__v":4,"createdAt":"2016-10-26T22:30:09.862Z","releaseDate":"2016-10-26T22:30:09.862Z","categories":["58112e72ded0340f0085d02b","58112e72ded0340f0085d02c","58112e72ded0340f0085d02d","58112e72ded0340f0085d02e","58112e72ded0340f0085d02f","58112e72ded0340f0085d030","58112e72ded0340f0085d031","58112e72ded0340f0085d032","58112e72ded0340f0085d033","58112e72ded0340f0085d034","581137cc604d3c230048b7e4","58dc367221742d0f00a73f98","590768e54669da0f00db5c0b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"new designer","version_clean":"2.0.0","version":"2.0"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-01T16:59:07.488Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Let's say we wanted to gather order and subscription information about a given Cratejoy customer.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4877577-Blank_Diagram_-_Page_1_1.png\",\n        \"Blank Diagram - Page 1 (1).png\",\n        1451,\n        1040,\n        \"#cacaca\"\n      ],\n      \"caption\": \"Customer Mapping, select properties included\"\n    }\n  ]\n}\n[/block]\nFor these purposes, let's presume that the customer has placed at least one subscription order.\n\n\n## Subscriptions \nA customer may have many **subscriptions**. Within a single subscription, a subscription will have just one of each of the following. \n\n* **Product**. Here, we could find what subscription product the customer is subscribed to, including product name, product ID, description, etc.\n\n* **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.\n\n* **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.\n\n* **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`.\n\nNote 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.\n\nAll 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.\n\n## Orders\nA single customer may have many orders, and subscriptions and orders can be many-to-many. For example:\n\n* **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`).\n\n* **Subscription to Order, Many-to-One**: An order in which a customer has purchased two different subscriptions.\n\n* **Subscription to Order, Many-to-Many**: The combination of the above cases!\nA 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. \n\n## Transactions\nAn 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).","excerpt":"","slug":"customers-to-orders-subs-shipments","type":"basic","title":"Customers to Orders, Subscriptions"}

Customers to Orders, Subscriptions


Let's say we wanted to gather order and subscription information about a given Cratejoy customer. [block:image] { "images": [ { "image": [ "https://files.readme.io/4877577-Blank_Diagram_-_Page_1_1.png", "Blank Diagram - Page 1 (1).png", 1451, 1040, "#cacaca" ], "caption": "Customer Mapping, select properties included" } ] } [/block] 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).