ScopeDescription
read_ordersRequired to read orders record.
write_ordersRequired to write to the orders record.

What is an Order?

Orders contain information about the line items in an order, the corresponding Recharge subscription ID for the order, and IDs for a corresponding order if one is created on an external eCommerce platform.

In our direct integrations, an order is created in Recharge after we've successfully processed a Charge. When using our API Integration, you should create an Order record in your external integration to maintain consistency between data in Recharge and on your external platform. See our guide on syncing orders via API integration for more information.

The orders resource also contains some information about the customer. See Addresses and Customers for detailed billing information.

At this time, you can only update orders that are prepaid queued order. These items have been paid ahead of time by the customer but are set to be delivered on a recurring cycle. An order contains all the same JSON data as the charge. In case of a prepaid order creation, the order will be queued for a particular date and submitted on that date to the external eCommerce platform.

Updating line items

You can only update line_item properties directly on the Orders object if it is a prepaid subscription.

To update an Order's line_items, you must update the corresponding Subscription, which will then generate a new Charge. You must make changes to the Order line_items this way because the values of this property are inherited from the Charge model.

🚧

Warning

When updating line_items you must provide all the JSON data that was in line_items before the update, as the data you provide in a PUT overrides the previous record and only new data will remain.

24012401

Order FAQ

If I create an order in Shopify through Shopify api what is needed for the order to appear on the Recharge order list?

In that case you should also create it in Recharge. You’d create the customer, address, and subscription which would schedule the next future charge. It’s the same concept as if you had added them manually via the Recharge UI.

Is there a way to add additional information to the order, that would appear in the line_items?

Yes. You will be able to leverage the line_items.properties on an order to store additional information. The attribute takes an array of name|value pairs.

Below some more details on how to proceed in order to add this information to orders.
line_items of an order is an inherited parameter from the charge object which itself is a collection of the subscriptions linked to this charge. When a charge is processed the properties are inherited by the resulting order(s).

There are 2 possible scenarios:

  • You want to add information to an order that already exists
    This is the case if you are using a prepaid subscription where all orders for the prepaid subscription are generated upon the payment of the subscription. Or alternatively you are looking to update an order whose charge has already been processed. In both cases there is an existing order object(s) for you to update.
    In this situation you will need to find the relevant object(s) and update them directly using the order update endpoint.

  • You are looking to add information to future orders
    In this case the order objects do not yet exist and you want those properties to be inherited by all future orders. Therefore you need to look for the corresponding subscription and update the subscription.properties with the relevant details you need to carry over on the future order(s).
    Any future charges involving this subscription will carry the properties of this subscription in its line_items.

But what about QUEUED charges? Upon subscription update we make sure to regenerate the charge objects in QUEUED state which are linked to this subscription and the new properties you added will be then appear on the regenerated charges.

Once the charges are processed at their scheduled_at time the order(s) will be generated and will contain the new properties in their line_items.

What does type stand for?

The type attribute helps characterise an order. It can take 2 values: CHECKOUT or RECURRING.

  • CHECKOUT - this means the order was placed through the checkout by the user
  • RECURRING - any order which is not a CHECKOUT

Why do some of my orders have value of null for shopify_order_id or external_order_id?

  • If you are not using an external order management platform
    This field will remain null as it is related to the reference to the matching order in your external order management platform.
  • If you are using an external order management platform (aka OMS)
    • If you are using one of our existing e-commerce integration
      The external_ order_id or shopify_order_id will only be populated once the order has been created in the OMS and we have received confirmation of the corresponding order_id in the OMS.
    • If you are using a custom OMS integration and you would like to make sure to keep track in Recharge of the corresponding order_ids in your OMS, you will need to make sure that the process you use to extract the orders generated in Recharge also update the said orders with the relevant ids.

Need Help? Contact Us