A few assumptions about relay orders api

[Andrey Bulgakov]

Hey,

I would really appreciate if someone on Stripe team confirmed or disapproved each of the following assumptions that I made about orders api:

1) "items" sub-collections of "orders" and "order_returns" resources are immutable – they cannot be changed once order has been created;

2) order of objects in those sub-collections is guaranteed – with every request "items" are always being received in the same order;

3) for every "item" within the "order" or "order_return" the "type" + "parent" tuple is unique;

4) there can be only one item with type=tax within a single "order" or "order_return";

I want to generate a unique id for every item in these sub-collections and trying to figure out which fields I can rely on.

Thanks.

[Remi J.]

Hey Andrey!

1) "items" sub-collections of "orders" and "order_returns" resources are immutable – they cannot be changed once order has been created;

=> That's mainly correct since you can't change them directly.

There is one exception, however: If you have multiple shipping options available on your order, picking a different shipping method will update the order items as well. For example, an order that offers $5 standard shipping and $10 express shipping will start out with a $5 standard shipping line item. If the customer picks express shipping later, Stripe replaces the $5 standard shipping line item with the $10 shipping line item and updates the order total.

Line items for `order_return` are ​always​ immutable.

2) order of objects in those sub-collections is guaranteed – with every request "items" are always being received in the same order;

=> In practice this is the case, but we don't really guarantee it. Since the space of `type`s is limited (sku, tax, shipping, discount), I would recommend displaying each of them in their own section or sorting based on those types instead of relying on the order of the items directly.

 

3) for every "item" within the "order" or "order_return" the "type" + "parent" tuple is unique;

=> This is actually slightly more complicated because only some order items have IDs. For example, `tax` items do not have a `parent` field usually, and it is perfectly acceptable for a merchant or a tax provider to return multiple tax line items. You could imagine returning both state and municipal tax on an order or including both VAT and local sales tax as two separate line items. We do guarantee that the tuple (type, parent, description) is unique, however. In practice, non-tax items will have a unique (type, parent) value.

 

4) there can be only one item with type=tax within a single "order" or "order_return";

=> There is no bound on the number of items, though you’re likely to only see one or two in practice.

Hope this helps!

Remi

 

I want to generate a unique id for every item in these sub-collections and trying to figure out which fields I can rely on.

Thanks.

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[Andrey Bulgakov]

Thanks Remi for your detailed explanation!