Orders

Accounting » Orders

Introduction

The Orders endpoint uses the OData standard with HATEOAS-style navigation links to expose data and allow querying of the specific information that is needed. It is read-only, and cannot be used to place or edit Orders.

While it is possible to pull all of the information contained within an Order at once, we recommend that you only retrieve the specific information that you need in order to ensure efficiency and scalability for your application.

How It Works

Resource Specifications

Order

Name	Description	Type	Additional information
Id	Unique identifier for the Order	string	Key
Type	Type of the order	EOrderType	None.
OrderDate	When the Order was placed, in local subscriber time	DateTime	ConcurrencyCheck
LocationId	Id of the location at which this order was created	string	None.
Purchaser	Person placing the Order	Purchaser	Contained
Items	The list of Items that are part of this Order	Collection of OrderItem	Contained
Cost	The cost of the Order	OrderCost	Contained
Payments	The list of Payments applied to the Order	Collection of Payment	Contained
LastModifiedTime	The time the Order was last modified in UTC	DateTimeOffset	None.
CreatedTime	The time the Order was created in UTC	DateTimeOffset	None.

EOrderType

Name	Value	Description
Sale	0	A Sale-type Order; this is the average case of a consumer purchasing goods or services
Refund	1	A Refund-type Order, in which goods or services were returned for a refund
Void	2	A Void-type Order, where the transactions were voided completely
VoidRefund	3	A Voided Refund-type Order, where the transaction in which goods or services were returned was voided

Purchaser

Name	Description	Type	Additional information
Id	Unique identifier for the Purchaser	string	Key
FirstName	First name of the Purchaser	string	None.
LastName	Last name of the Purchaser	string	None.

OrderItem

Name	Description	Type	Additional information
Id	Unique identifier for this Item in the context of the Order	string	Key
OrderId	Foreign key reference to the Order this Item is a part of	string	None.
Name	Display name for the Item	string	None.
Quantity	Multiplier for the number of identical items that were sold in this OrderItem. Note that this functionality is deprecated; going forward, each distinct item sold should have its own OrderItem.	int	None.
Cost	The cost of the Order Item	OrderItemCost	Contained

OrderItemCost

Name	Description	Type	Additional information
OrderItemId	Foreign key reference to the Order Item this Order Item Cost is for	string	None.
NetPrice	Base price of the Order Item without discounts or taxes	decimal	None.
AskingPrice	The price that was set as the base price by the business and that the consumer agreed to. This is the same as NetPrice in non vat subscribers. In vat subscribers this price is different since taxes are included in their asking price. This is the price that would be user settable in certain instances depending on permissions	decimal	None.
ItemTotal	The computed actual amount being paid in total for this item including taxes and discounts	decimal	None.
RevenueCategoryId	The reference to the Revenue Category	string	Contained
Discounts	Discounts that were applied to the Order Item, Up to 1	Collection of Discount	Contained
NoTax	Designates whether the item was sold with the "No Tax" option specified Warning: value not valid on Orders of type "Void" or "VoidReturn"	bool	None.
Taxes	Tax Rates that were applied to the Order Item, Up to 5	OrderItemTax	Contained
Payments	Payments that were applied to the Order Item	OrderItemPayment	Contained

Discount

Name	Description	Type	Additional information
Amount	The amount of the discount	decimal	None.
Percentage	The precentage it took from the item	double	None.
RedemptionCode	Any redemption code that was used for this discount	string	None.
DiscountReferenceId	Reference to the Discount	string	None.

OrderItemTax

Name	Description	Type	Additional information
OrderItemId	Foreign key reference to the Order Item this Tax is for	string	None.
TaxNumberReference	A reference to the tax that was applied. Valid values are 1-5 inclusive.	string	None.
Amount	The amount of the tax	decimal	None.

OrderItemPayment

Name	Description	Type	Additional information
Id	Unique identifier for the OrderItemPayment	string	Key
OrderItemId	Reference to the Order Item this paid for	string	None.
PaymentId	Reference to the overall Payment that was made, of which this may only be part	string	None.
Amount	The amount from the Payment that was applied to the Order Item	decimal	None.
DiscountAmount	The discount amount attributed to this Order Item Payment	decimal	None.
TaxAmounts	The tax amounts attributed to this Order Item Payment	Collection of decimal	None.

OrderCost

Name	Description	Type	Additional information
OrderId	Foreign key reference to the Order this Cost pertains to	string	Key
Total	The total amount that was paid	decimal	None.
Tax	The total tax that was paid	decimal	None.
Discount	The total discount that was applied	decimal	None.
Shipping	The total shipping cost that was applied	decimal	None.

Payment

Name	Description	Type	Additional information
Id	Unique identifer for the Payment	string	Key
OrderId	Foreign key reference to the Order this Payment was applied to	string	None.
PaymentMethodId	The reference to the Payment Method	string	None.
Amount	The amount that was recorded for the Payment	decimal	None.

Permissions

Currently, only users with the role of MINDBODY Owner and the MINDBODY Automated System have permission to access this resource.

How To Use It

Scoping

Every request to the Orders endpoint must be scoped; a URL convention is used to specify the request scope. Currently the only supported scope type is subscriber, so every request must include the subscriber id. Requests should look like:
https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders, where {subscriberId} is the supplied subscriber id.

odata.metadata=full

You can use the $format parameter to specify the verbosity of the output; supplying "odata.metadata=full" will ensure all possible OData links are returned in the payload.

For example, the following request:
https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders?$format=application/json;odata.metadata=full
will return a payload that looks like the following:

{
    "@odata.context":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/$metadata#Orders",
    "@odata.count":1234,
    "value":[
        {
            "@odata.type":"#subscriber.mindbodyonline.com.Order",
            "@odata.id":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')",
            "@odata.etag":"W/\"XXXXXXXXXXXXX\"",
            "@odata.editLink":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')",
            "Id":"{orderId}",
            "[email protected]":"#Mindbody.Api.Subscriber.Areas.Accounting.Models.EOrderType",
            "Type":"{orderType}",
            "[email protected]":"#DateTimeOffset",
            "OrderDate":"{orderDate}",
            "LocationId":"{locationId}",
            "[email protected]":"#DateTimeOffset",
            "LastModifiedTime":"{lastModifiedTime}",
            "[email protected]":"#DateTimeOffset",
            "CreatedTime":"{createdTime}",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Purchaser/$ref",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Purchaser",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Items/$ref",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Items",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Cost/$ref",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Cost",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Payments/$ref",
            "[email protected]":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders('{orderId}')/Payments"
        },
        ...
    ],
    "@odata.nextLink":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders?$format=application/json;odata.metadata=full&$skip=50&$top=50"
}

Paging

Paging is crucial when using the Orders endpoint, because there is potentially a lot of retrievable data. The server enforces a max page size of 100, and we recommend a page size of 50.

Note, in the example above (under odata.metadata=full), the $skip and $top parameters specified in the nextLink. In the event that there are more Orders than the $top specified in the original request (or 50, if no $top was specified) - which is the case in the example, since the total count of Orders is 1,234 - a nextLink is provided with $skip and $top parameters that will provide you with the next page of results. Upon submitting a request to the nextLink URL, you would receive a payload that looks like the following:
```
{
    "@odata.context":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/$metadata#Orders",
    "@odata.count":1234,
    "value":[
        ...
    ],
    "@odata.nextLink":"https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders?&$skip=100&$top=50"
}
```
And you could continue navigating the provided nextLinks until you have retrieved all 1,234 Orders.
Filtering

It is recommended to provide specific filters when accessing Orders, since there can be a great store of data and you are unlikely to get what you actually need without narrowing the scope a little. Targeting the specific information you need will also increase the performance for your app.

The simplest (and recommended) way to limit the results is based on time - either when Orders were created or when they were last modified. If you wanted to retrieve all Orders processed since yesterday, for example, you would submit the following request:
https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders?&$filter=LastModifiedTime ge 2024-11-20T00:00:00.0000000Z

Tip: When building requests with time filters from C# code, you can utilize the built-in DateTime formatter "ToString("o")" in order to get a properly formatted parameter value. Also, remember that the CreatedTime and LastModifiedTime properties are in UTC!

See also the section in the OData docs on Primitive Literals for more examples of how to represent filter values in your queries.
Fetching Contained Resources

You have 2 options when trying to fetch the data contained within the Orders resource. As you can see in the example from the odata.metadata=full section, you can utilize navigation links to drill down into the contained resources.

You can also utilize the $expand parameter in order to retrieve the information you need. Doing it this way allows for slightly more flexibility, because you can specify all the information you need at once (if you need more than one of the contained resources on an Order) For example, retrieving both the Items and Payments on the Order would look like:
https://subscriber.mindbodyonline.com/odata/v4/Subscriber_{subscriberId}/Orders?$expand=Items,Payments