# API # General # What are the available endpoints? #### Orders
**Method****Endpoint****Permission****Description**
`GET``/api/orders``orders.index`List orders
`GET``/api/orders/{id}``orders.view`Get an order
`POST``/api/orders``orders.store`Create an order
`POST``/api/orders/{id}/flags/{id}``orders.flags.store`Attach a flag
`DELETE``/api/orders/{id}/flags/{id}``orders.flags.delete`Remove a flag
`POST``/api/orders/{id}/comments``orders.comments.store`Add a comment

You can pass the order `reference` in place of `id`.

You can pass the flag `name` in place of the `id`.

#### Fulfillments
**Method****Endpoint****Permission****Description**
`POST``/api/orders/{id}/fulfillments``fulfillments.store`Create a fulfillment
`DELETE``/api/orders/{id}/fulfillments/{id}``fulfillments.delete`Cancel a fulfillment

You can pass the order `reference` in place of `id`.

You can pass the fulfillment `reference` in place of `id`.

#### Order Statuses
**Method****Endpoint****Permission****Description**
`GET``/api/order-statuses``order-statuses.index`List order statuses
`GET``/api/order-statuses/{id}``order-statuses.view`Get an order status
#### Products
**Method****Endpoint****Permission****Description**
`GET``/api/products``products.index`List products
`GET``/api/products/search``products.search`Search products
`GET``/api/products/{id}``products.view`Get a product
`POST``/api/products``products.store`Create a product
`PUT``/api/products/{id}``products.update`Update a product

You can pass the product `model` in place of `id`.

The `search` route allows for filtering at document level rather than eloquent level.

#### Variants
**Method****Endpoint****Permission****Description**
`POST``/api/products/{id}/variants``variants.store`Create a variant
`PUT``/api/products/{id}/variants/{id}``variants.update`Update a variant

You can pass the product `model` in place of `id`.

You can pass the variant `sku` in place of `id`.

#### Manufacturers
**Method****Endpoint****Permission****Description**
`GET``/api/manufacturers``manufacturers.index`List manufacturers
`GET``/api/manufacturers/{id}``manufacturers.view`Get a manufacturer
`POST``/api/manufacturers``manufacturers.store`Create a manufacturer
`PUT``/api/manufacturers/{id}``manufacturers.update`Update a manufacturer
`DELETE``/api/manufacturers/{id}``manufacturers.delete`Delete a manufacturer

You can pass the manufacturer `name` in place of `id`.

#### Attribute Groups
**Method****Endpoint****Permission****Description**
`GET``/api/attribute-groups``attribute-groups.index`List attribute groups
`GET``/api/attribute-groups/{id}``attribute-groups.view`Get an attribute group
`POST``/api/attribute-groups``attribute-groups.store`Create an attribute group
`PUT``/api/attribute-groups/{id}``attribute-groups.update`Update an attribute group
`DELETE``/api/attribute-groups/{id}``attribute-groups.delete`Delete an attribute group

You can pass the attribute group `name` in place of `id`.

#### Attributes
**Method****Endpoint****Permission****Description**
`POST``/api/attribute-groups/{id}/attributes``attributes.store`Create an attribute
`PUT``/api/attribute-groups/{id}/attributes/{id}``attributes.update`Update an attribute
`DELETE``/api/attribute-groups/{id}/attributes/{id}``attributes.delete`Delete an attribute

You can pass the attribute group `name` in place of `id`.

You can pass the attribute `name` in place of `id`.

#### Categories
**Method****Endpoint****Permission****Description**
`GET``/api/categories``categories.index`List categories
`GET``/api/categories/{id}``categories.view`Get a category
`POST``/api/categories``categories.store`Create a category
`PUT``/api/categories/{id}``categories.update`Update a category
`DELETE``/api/categories/{id}``categories.delete`Delete a category

You can pass the category `name` or `breadcrumb` in place of `id`.

#### Tag Groups
**Method****Endpoint****Permission****Description**
`GET``/api/tag-groups``tag-groups.index`List tag groups
`GET``/api/tag-groups/{id}``tag-groups.view`Get a tag group
`POST``/api/tag-groups``tag-groups.store`Create a tag group
`PUT``/api/tag-groups/{id}``tag-groups.update`Update a tag group
`DELETE``/api/tag-groups/{id}``tag-groups.delete`Delete a tag group

You can pass the tag group `name` in place of `id`.

#### Tags
**Method****Endpoint****Permission****Description**
`POST``/api/tag-groups/{id}/tags``tags.store`Create a tag
`PUT``/api/tag-groups/{id}/tags/{id}``tags.update`Update a tag
`DELETE``/api/tag-groups/{id}/tags/{id}``tags.delete`Delete a tag

You can pass the tag group `name` in place of `id`.

You can pass the tag `name` in place of `id`.

#### Collections
**Method****Endpoint****Permission****Description**
`GET``/api/collections``collections.index`List collections
`GET``/api/collections/{id}``collections.view`Get a collection
`POST``/api/collections``collections.store`Create a collection
`PUT``/api/collections/{id}``collections.update`Update a collection
`DELETE``/api/collections/{id}``collections.delete`Delete a collection

You can pass the collection `name` in place of `id`.

#### Customers
**Method****Endpoint****Permission****Description**
`GET``/api/customers``customers.index`List customers
`GET``/api/customers/{id}``customers.view`Get a customer
`POST``/api/customers``customers.store`Create a customer
`PUT``/api/customers/{id}``customers.update`Update a customer
#### Addresses
**Method****Endpoint****Permission****Description**
`POST``/api/customers/{id}/addresses``addresses.store`Create an address
`PUT``/api/customers/{id}/addresses/{id}``addresses.update`Update an address
`DELETE``/api/customers/{id}/addresses/{id}``addresses.delete`Delete an address
#### Payment Methods
**Method****Endpoint****Permission****Description**
`GET``/api/payment-methods``payment-methods.index`List payment methods
`GET``/api/payment-methods/{id}``payment-methods.view`Get a payment method
#### Shipping Methods
**Method****Endpoint****Permission****Description**
`GET``/api/shipping-methods``shipping-methods.index`List shipping methods
`GET``/api/shipping-methods/{id}``shipping-methods.view`Get a shipping method
#### Locations
**Method****Endpoint****Permission****Description**
`GET``/api/locations``locations.index`List locations
`GET``/api/locations/{id}``locations.view`Get a location
`POST``/api/locations``locations.store`Create a location
`PUT``/api/locations/{id}``locations.update`Update a location

You can pass the location `name` in place of `id`.

#### Flags
**Method****Endpoint****Permission****Description**
`GET``/api/flags``flags.index`List flags
`GET``/api/flags/{id}``flags.view`Get a flag
`POST``/api/flags``flags.store`Create a flag
`PUT``/api/flags/{id}``flags.update`Update a flag
`DELETE``/api/flags/{id}``flags.delete`Delete a flag

You can pass the flag `name` in place of `id`.

#### Price Lists
**Method****Endpoint****Permission****Description**
`GET``/api/price-lists``price-lists.index`List price lists
`GET``/api/price-lists/{id}``price-lists.view`Get a price list
`POST``/api/price-lists``price-lists.store`Create a price list
`PUT``/api/price-lists/{id}``price-lists.update`Update a price list
#### Price List Entries
**Method****Endpoint****Permission****Description**
`POST``/api/price-lists/{id}/entries``price-list-entries.store`Create a price list entry
`PUT``/api/price-lists/{id}/entries/{id}``price-list-entries.update`Update a price list entry
#### Specification Groups
**Method****Endpoint****Permission****Description**
`GET``/api/specification-groups``specification-groups.index`List specification groups
`GET``/api/specification-groups/{id}``specification-groups.view`Get a specification group
`POST``/api/specification-groups``specification-groups.store`Create a specification group
`PUT``/api/specification-groups/{id}``specification-groups.update`Update a specification group

Must have installed `aerocargo/specifications` for these endpoints to work.

#### Upsell Groups
**Method****Endpoint****Permission****Description**
`GET``/api/upsell-groups``upsell-groups.index`List upsell groups
`GET``/api/upsell-groups/{key}``upsell-groups.view`Get an upsell group
`POST``/api/upsell-groups``upsell-groups.store`Create an upsell group
`PUT``/api/upsell-groups/{key}``upsell-groups.update`Update an upsell group

Must have installed `aerocargo/upsells` for these endpoints to work.

#### Listing Collection Groups
**Method****Endpoint****Permission****Description**
`GET``/api/listing-collection-groups``listing-collection-groups.index`List listing collection groups
`GET``/api/listing-collection-groups/{key}``listing-collection-groups.view`Get a listing collection group
`POST``/api/listing-collection-groups``listing-collection-groups.store`Create a listing collection group
`PUT``/api/listing-collection-groups/{key}``listing-collection-groups.update`Update a listing collection group

Must have installed `aerocargo/listing-collections` for these endpoints to work.

#### Stock
**Method****Endpoint****Permission****Description**
`POST``/api/stock``stock.update`Bulk update variant stock
# What conventions does the API use? #### Attribute Conventions - Keys generally match the attribute name on their respective models. - **Exception:** Attributes ending in "\_code" should omit the suffix when passed to the API, e.g. `currency_code` => `currency` #### Relationship Conventions - Nested data should use a **snake\_case** version of the relationship method name where present, e.g.: `shippingMethod` => `shipping_method` #### Price Conventions - Prices retrieved from the API are mostly in the currency's smallest unit, e.g. `1000` = `10 GBP` - Prices should generally be provided in the currency’s standard unit, e.g. `10` = `10 GBP` (unless otherwise stated) - Prices should generally be passed as an object, e.g.: ``` { "price": { "amount": 400, // Excluding tax "tax": 80 } } ``` **Exception:** Some endpoints support passing a single tax-inclusive value: ``` { "price": 480 // Including tax } ``` See the relevant endpoint docs to see if this is supported for an endpoint #### Date Conventions - Dates must be **Carbon-parseable**, supported formats include: - 2023-09-01T09:29:41.000000Z - 2023-09-01 09:29:41 - 2023-09-01 (defaults to midnight if no time is provided) #### Pagination Conventions
**Parameter** **Description** **Example**
`page`The page number (default: 1)`?page=2`
`per_page`The number of results per page (default: 24, max: 96)`?per_page=48`
`ids`Comma-separated list of IDs to fetch`?ids=1,2,5`
`min_updated_at`The min updated at for a product`?min_updated_at=2023-08-30%2010:35:05`
`max_updated_at`The max updated at for a product`?max_updated_at=2023-08-30%2010:35:05`

The `min_updated_at` and `max_updated_at` parameters are only supported by index endpoints.

Responses follow Laravel's pagination format, e.g.: ``` { "current_page": 1, "data": [ //... ], "first_page_url": "http://aero.test/api/products?page=1", "from": 1, "last_page": 2, "last_page_url": "http://aero.test/api/products?page=2", "next_page_url": "http://aero.test/api/products?page=2", "path": "http://aero.test/api/products", "per_page": 24, "prev_page_url": null, "to": 24, "total": 29 } ``` #### Scope Conventions - Index endpoints support a scope parameter, which is a comma-separated list of scopes. - Supported scopes are endpoint-specific and documented in endpoint-specific example docs. #### Image Factory Conventions
**Parameter** **Description** **Example**
`image_factory_width`Output image width`?image_factory_width=200`
`image_factory_height`Output image height`?image_factory_height=200`
`image_factory_options`Comma-seperated options`?image_factory_options=flip,greyscale`

If any of these query parameters are present in the GET requests, Image Factory will be applied.

# What responses does the API return?
**Code** **Scenario**
`200 Success`The request was processed successfully.
`201 Created` One (or multiple) resources were created.
`400 Bad Request` Cannot process request due to client error.
`401 Unauthorised` Invalid bearer token provided.
`404 Not Found` Endpoint not found.
`422 Unprocessable Content` Payload failed validation.
`500 Internal Server Error`
#### Examples ##### `200 Success` ``` GET /api/orders/{id} ``` ```json { "reference": "ABC123", "email": "acme@aerocommerce.com", "subtotal": { "amount": 84166.67, "tax": 16833.33 }, "shipping": { "amount": 83.33, "tax": 16.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "surcharge": { "amount": 0, "tax": 0 }, "ordered_at": "2023-09-01T09:29:41.000000Z", "deliver_on": null, "currency": "GBP", "status": { "id": 3, "name": "Successful", "state": "successful" }, "customer": { "id": 1, "name": "Acme", "email": "acme@aerocommerce.com" }, "shipping_method": { "id": 1, "name": "Standard" }, "billing_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "reference": null, "country": "GB", "eori_number": null }, "shipping_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "reference": null, "country": "GB", "eori_number": null }, "items": [ { "id": 1, "name": "Test", "sku": "TEST-S", "product_id": 4, "variant_id": 14, "shippable": true, "quantity": 2, "price": { "amount": 42083.33, "tax": 8416.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "full_price": { "amount": 42083.33, "tax": 8416.67 }, "weight": 0, "volume": 0 } ] } ``` ##### `201 Created` ``` POS /api/orders ``` ```json { "order": { "id": 15 } } ``` ##### `400 Bad Request` ``` GET /api/orders/{id} ``` ```json { "message": "Missing order ID" } ``` ##### `401 Unauthorised` ``` GET /api/orders/{id} ``` ```json { "message": "Unauthorized: Bearer token missing." } ``` ##### `404 Not Found` ``` GET /api/orders/{id} ``` ```json { "message": "The requested order with ID {id} could not be found." } ``` ##### `422 Unprocessable Content` ``` POST /api/orders ``` ```json { "message": "The given data was invalid.", "errors": { "currency": ["The currency field is required."] } } ``` ##### `500 Internal Server Error` ```json { "message": "Exception message..." } ``` # Orders # Order Index Endpoint This endpoint retrieves a paginated list of all orders #### Structure See [`Order View Endpoint`](https://support.aerocommerce.com/books/api/page/order-view-endpoint) for the structure of the order payload inside the `data` array. --- #### Scopes
**Name** **Description** **Example**
`visible`Only return visible orders (those which have been ordered)`?scope=visible`
`outstanding`Only return outstanding orders`?scope=outstanding`
`completed`Only return completed orders`?scope=completed`
`incomplete`Only return incomplete orders`?scope=incomplete`
`express`Only return express orders`?scope=express`
`standard`Only return standard orders`?scope=standard`
--- #### Filters
**Name** **Description** **Example**
`reference`Only return orders with specific references`?references=ABC123,DEF456`
`statuses`Only return orders with specific status ids or names`?statuses=1,On Hold`
`states`Only return orders with specific states`?states=dispatched,returned`
`customers`Only return orders with specific customers (by id or email)`?customers=1,test@gmail.com`
`emails`Only return orders for specific emails`?emails=test@gmail.com`
`channels`Only return orders for specific channels`?channels=web,api`
`flags`Only return orders for specific flags (by `id`, `name`, or `name|value`)`?flags=1,abc,def|123`
--- ``` GET /api/orders?per_page=2&min_ordered_at=2023-08-30%2010:36:23 ``` ```json { "current_page": 1, "data": [ //... ], "first_page_url": "http://aero.test/api/orders?page=1", "from": 1, "last_page": 3, "last_page_url": "http://aero.test/api/orders?page=3", "next_page_url": "http://aero.test/api/orders?page=2", "path": "http://aero.test/api/orders", "per_page": 2, "prev_page_url": null, "to": 2, "total": 5 } ```

See [`Order View Endpoint`](https://support.aerocommerce.com/books/api/page/order-view-endpoint) for the structure of the order payload inside the `data` array.

# Order View Endpoint This endpoint retrieves a single order by `id` or `reference`. #### Structure ##### Order
**Name** **Type** **Description**
`reference`stringThe **unique** reference for the order
`status`objectThe [Order Status](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-order-status) of the order (`null` if none)
`customer`objectThe [Customer](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-customer) of the order (`null` if none)
`email`stringThe email of the customer that placed the order
`subtotal.amount`floatThe subtotal of the order **excluding tax**
`subtotal.tax`floatThe subtotal tax for the order
`shipping.amount`floatThe shipping of the order **excluding tax**
`shipping.tax`floatThe shipping tax for the order
`discount.amount`floatThe discount of the order **excluding tax**
`discount.tax`floatThe discount tax for the order
`surcharge.amount`floatThe surcharge of the order **excluding tax**
`surcharge.tax`floatThe surcharge tax for the order
`currency`stringThe currency code of the order
`shipping_method`objectThe [Shipping Method](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-shipping-method) of the order (`null` if none)
`shipping_address`objectThe [Shipping Address](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-shipping-address) of the order (`null` if none)
`billing_address `objectThe [Billing Address](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-billing-address) of the order (`null` if none)
`ordered_at`timestampWhen the order was ordered
`deliver_on`timestampWhen the order should be delivered
`items`arrayAn array of [Order Item](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-order-item) objects
`payments`arrayAn array of [Payment](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-payment) objects
`fulfillments`arrayAn array of [Fulfillment](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-fulfillment) objects
`returns`arrayAn array of [Return](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-return) objects
`comments`arrayAn array of [Comment](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-comment) objects
`additional_attributes`arrayAn array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-additional-attribute) objects
##### Order Status
**Name** **Type** **Description**
`id`intThe id of the order status
`name`stringThe name of the order status
`state`stringThe state of the order status
**Valid states:** cancelled, on\_hold, successful, complete, processing, closed, partially\_dispatched, dispatched, partially\_returned, returned ##### Customer
**Name** **Type** **Description**
`id`intThe id of the customer
`name`stringThe name of the customer
`email`stringThe email of the customer
##### Shipping Method
**Name** **Type** **Description**
`id`intThe id of the shipping method
`name`stringThe name of the shipping method
##### Shipping Address
**Name** **Type** **Description**
`first_name`stringThe first name for the shipping address
`last_name`stringThe last name for the shipping address
`company`stringThe company for the shipping address
`mobile`stringThe mobile number for the shipping address
`phone`stringThe phone number for the shipping address
`line_1`stringThe first line for the shipping address
`line_2`stringThe second line for the shipping address
`city`stringThe city for the shipping address
`county`stringThe county for the shipping address
`zone`stringThe zone code for the shipping address
`postcode`stringThe postcode for the shipping address
`country`stringThe country code for the shipping address
`reference`stringThe **unique** reference for the shipping address
`eori_number`stringThe EORI number for the shipping address
##### Billing Address
**Name** **Type** **Description**
`first_name`stringThe first name for the billing address
`last_name`stringThe last name for the billing address
`company`stringThe company for the billing address
`mobile`stringThe mobile number for the billing address
`phone`stringThe phone number for the billing address
`line_1`stringThe first line for the billing address
`line_2`stringThe second line for the billing address
`city`stringThe city for the billing address
`county`stringThe county for the billing address
`zone`stringThe zone code for the billing address
`postcode`stringThe postcode for the billing address
`country`stringThe country code for the billing address
`reference`stringThe **unique** reference for the billing address
`eori_number`stringThe EORI number for the billing address
##### Order Item
**Name** **Type** **Description**
`id`intThe id of the order item
`variant_id`intThe variant id of the buyable (not set if the buyable is not a variant)
`product_id`intThe product id of the buyable
`buyable_type`stringThe buyable type of the order item
`buyable_id`intThe buyable id of the order item
`name`stringThe name for the order item
`url`stringThe url for the order item
`sku`stringThe sku for the order item
`reference`stringThe **unique** reference for the order item
`manufacturer`objectThe [Manufacturer](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-manufacturer) for the order item (`null` if none)
`image.url`stringThe image url for the order item
`shippable`booleanWhether the order item is shippable
`quantity`intThe quantity for the order item
`returned_quantity`intThe quantity returned for the order item
`price.amount`floatThe **unit** price of the order item **excluding tax**
`price.tax`floatThe **unit** tax for the order item
`discount.amount`floatThe **total** discount of the order item **excluding tax**
`discount.tax`floatThe **total** discount tax for the order item
`full_price.amount`floatThe **unit** full price (including extras) of the order item **excluding tax**
`full_price.tax`floatThe **unit** full tax (including extras) for the order item
`cost_price.amount`floatThe **unit** cost price of the order item **excluding tax**
`cost_price.currency`stringThe currency code for the cost price
`weight`floatThe weight for the order item
`weight_unit`floatThe weight unit for the order item, defaults to stores normalized weight unit
`volume`floatThe volume for the order item
`volume_unit`floatThe volume unit for the order item, defaults to stores normalized volume unit
`hs`stringThe HS code for the order item
`origin_country`stringThe origin country code for the order item
`goods_description`stringThe goods description for the order item
##### Manufacturer
**Name** **Type** **Description**
`id`intThe id of the manufacturer
`name`stringThe name of the manufacturer
##### Payment
**Name** **Type** **Description**
`id`intThe id of the payment
`method`objectThe [Payment Method](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-payment-method) for the payment
`reference`stringThe reference for the payment
`state`stringThe state of the payment
`amount`floatThe total amount for the payment
`currency`stringThe currency code for the payment
`captured_at`timestampThe date the payment was captured
##### Payment Method
**Name** **Type** **Description**
`id`intThe id of the payment method
`name`stringThe name of the payment method
`driver`stringThe driver of the payment method
##### Fulfillment
**Name** **Type** **Description**
`id`intThe id of the order return
`method`objectThe [Fulfillment Method](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-fulfillment-method) for the fulfillment
`reference`stringThe reference of the fulfillment
`state`stringThe state of the fulfillment
`mobile`stringThe mobile number for the fulfillment
`phone`stringThe phone number for the fulfillment
`tracking_code`stringThe tracking code for the fulfillment
`tracking_url`stringThe tracking url for the fulfillment
`weight`floatThe weight for the fulfillment
`weight_unit`stringThe weight unit for the fulfillment, defaults to stores normalized weight unit
`volume`floatThe volume for the order item
`volume_unit`stringThe volume unit for the fulfillment, defaults to stores normalized volume unit
`delivery_note`stringThe delivery note for the fulfillment
`created_at`timestampThe date the fulfillment was made
`items`arrayAn array of [Fulfillment Items](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-fulfillment-items) objects
##### Fulfillment Method
**Name** **Type** **Description**
`id`intThe id of the fulfillment method
`name`stringThe name of the fulfillment method
`driver`stringThe driver of the fulfillment method
##### Fulfillment Items
**Name** **Type** **Description**
`id`intThe id of the order item that was fulfilled
`quantity`intThe quantity of the order item that was fulfilled
##### Return
**Name** **Type** **Description**
`id`intThe id of the order return
`reason`stringThe reason for the return - `null` if no reason given
`created_at`timestampThe date the return was made
`items`arrayAn array of [Return Item](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-return-item) objects
##### Return Item
**Name** **Type** **Description**
`id`intThe id of the order item that was returned
`quantity`intThe quantity of the order item that was returned
`exchanged_for_id`intThe id of the order item that the item was returned for (`null` if the item was not exchanged)
##### Comment
**Name** **Type** **Description**
`admin`objectThe [Admin](https://support.aerocommerce.com/books/api/page/order-view-endpoint#bkmrk-admin) who commented
`message`stringThe comment message
`customer_facing`booleanWhether the comment is customer facing
`created_at`timestampThe date the comment was created
##### Admin
**Name** **Type** **Description**
`id`intThe id of the admin
`name`stringThe name of the admin
`email`stringThe email of the admin
##### Additional Attribute
**Name** **Type** **Description**
`key`stringThe key of the additional attribute
`value`stringThe value of the additional attribute
--- #### Example Requests
Unfulfilled & Unreturned Order ``` GET /api/orders/{id|reference} ``` ```json { "id": 1, "reference": "ABC123", "email": "testing@gmail.com", "subtotal": { "amount": 84166.67, "tax": 16833.33 }, "shipping": { "amount": 83.33, "tax": 16.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "surcharge": { "amount": 0, "tax": 0 }, "ordered_at": "2023-09-01T09:29:41.000000Z", "deliver_on": null, "currency": "GBP", "status": { "id": 3, "name": "Successful", "state": "successful" }, "customer": { "id": 1, "name": "Test", "email": "test@gmail.com" }, "shipping_method": { "id": 1, "name": "Standard" }, "billing_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "reference": null, "country": "GB", "eori_number": null }, "shipping_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "reference": null, "country": "GB", "eori_number": null }, "items": [ { "id": 148, "name": "Sandro Paris Checked Trench Coat", "sku": "SHPMA00148-M", "product_id": 4, "variant_id": 14, "shippable": true, "quantity": 2, "price": { "amount": 42083.33, "tax": 8416.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "full_price": { "amount": 42083.33, "tax": 8416.67 }, "weight": 0, "volume": 0 } ], "payments": [ { "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "method": { "id": 1, "name": "Cash", "driver": "cash" }, "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "amount": 91000, "currency": "GBP", "captured_at": "2023-09-12T10:17:03.000000Z" } ], "fulfillments": [], "returns": [], "comments": [ { "admin": { "id": 1, "name": "Admin", "email": "admin@example.com" }, "message": "This is an API message", "customer_facing": true, "created_at": "2025-09-01 09:29:41" } ] } ```
Fulfilled Order ``` GET /api/orders/{id|reference} ``` ```json { "id": 1, "reference": "ABC123", "email": "testing@gmail.com", "subtotal": { "amount": 84166.67, "tax": 16833.33 }, "shipping": { "amount": 83.33, "tax": 16.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "surcharge": { "amount": 0, "tax": 0 }, "currency": "GBP", "ordered_at": "2023-09-01T08:29:41.000000Z", "deliver_on": null, "status": { "id": 6, "name": "Dispatched", "state": "dispatched" }, "customer": { "id": 1, "name": "Test", "email": "test@gmail.com" }, "shipping_method": { "id": 1, "name": "Standard" }, "billing_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "shipping_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "items": [ { "id": 26, "name": "Sandro Paris Checked Trench Coat", "url": "/product/sandro-paris-checked-trench-coat-4?variant=2", "sku": "SHPMA00148-M", "reference": null, "manufacturer": { "id": 2, "name": "Sandro Paris" }, "image": { "url": "http://l9.test/storage/images/products/uaaVbTbqbZxs1FH3N28Tw0a7dc6I7Xd08DiyPAG6.jpg" }, "product_id": 4, "variant_id": 14, "buyable_type": "variant", "buyable_id": 14, "shippable": true, "quantity": 2, "returned_quantity": 0, "price": { "amount": 42083.33, "tax": 8416.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "full_price": { "amount": 42083.33, "tax": 8416.67 }, "weight": 0, "volume": 0, "cost_price": { "amount": null, "currency": null }, "hs": null, "origin_country": null, "goods_description": null } ], "flags": [], "payments": [ { "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "method": { "id": 1, "name": "Cash", "driver": "cash" }, "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "state": "captured", "amount": 91000, "currency": "GBP", "captured_at": "2023-09-12T10:17:03.000000ZZ", "refunds": [] } ], "fulfillments": [ { "id": 3, "method": { "id": 1, "name": "Manual Fulfillment", "driver": "manual" }, "address": { "id": 3, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "reference": "F3-128", "state": "successful", "mobile": null, "email": "testing@gmail.com", "tracking_code": "test tracking code", "tracking_url": null, "weight": 0, "weight_unit": null, "volume": 0, "volume_unit": "cm^3", "delivery_note": "test delivery note", "created_at": "2023-09-12T10:17:03.000000Z", "items": [ { "id": 26, "quantity": 2 } ] } ], "returns": [], "comments": [] } ```
Returned Order (Exchange) ``` GET /api/orders/{id|reference} ``` ```json { "id": 1, "reference": "ABC123", "email": "testing@gmail.com", "subtotal": { "amount": 84166.67, "tax": 16833.33 }, "shipping": { "amount": 83.33, "tax": 16.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "surcharge": { "amount": 0, "tax": 0 }, "currency": "GBP", "ordered_at": "2023-09-01T08:29:41.000000Z", "deliver_on": null, "status": { "id": 7, "name": "Partially Returned", "state": "partially_returned" }, "customer": { "id": 1, "name": "Test", "email": "test@gmail.com" }, "shipping_method": { "id": 1, "name": "Standard" }, "billing_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "shipping_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "items": [ { "id": 26, "name": "Sandro Paris Checked Trench Coat", "url": "/product/sandro-paris-checked-trench-coat-4?variant=2", "sku": "SHPMA00148-M", "reference": null, "manufacturer": { "id": 2, "name": "Sandro Paris" }, "image": { "url": "http://l9.test/storage/images/products/uaaVbTbqbZxs1FH3N28Tw0a7dc6I7Xd08DiyPAG6.jpg" }, "product_id": 4, "variant_id": 14, "buyable_type": "variant", "buyable_id": 14, "shippable": true, "quantity": 2, "returned_quantity": 0, "price": { "amount": 42083.33, "tax": 8416.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "full_price": { "amount": 42083.33, "tax": 8416.67 }, "weight": 0, "volume": 0, "cost_price": { "amount": null, "currency": null }, "hs": null, "origin_country": null, "goods_description": null } ], "flags": [], "payments": [ { "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "method": { "id": 1, "name": "Cash", "driver": "cash" }, "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "state": "captured", "amount": 91000, "currency": "GBP", "captured_at": "2023-09-12T10:17:03.000000ZZ", "refunds": [] } ], "fulfillments": [], "returns": [ { "id": 1, "reason": "Test Reason", "created_at": "2023-09-12T10:17:03.000000ZZ", "items": [ { "id": 26, "quantity": 2, "exchanged_for_id": 27 } ] } ], "comments": [] } ```
Returned Order (Refund) ``` GET /api/orders/{id|reference} ``` ```json { "id": 1, "reference": "ABC123", "email": "testing@gmail.com", "subtotal": { "amount": 84166.67, "tax": 16833.33 }, "shipping": { "amount": 83.33, "tax": 16.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "surcharge": { "amount": 0, "tax": 0 }, "currency": "GBP", "ordered_at": "2023-09-01T08:29:41.000000Z", "deliver_on": null, "status": { "id": 8, "name": "Returned", "state": "returned" }, "customer": { "id": 1, "name": "Test", "email": "test@gmail.com" }, "shipping_method": { "id": 1, "name": "Standard" }, "billing_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "shipping_address": { "id": 1, "first_name": "Aero", "last_name": "Commerce", "company": "Aero Commerce", "mobile": null, "phone": null, "line_1": "28-32 Albert Rd", "line_2": null, "city": "Middlesbrough", "zone": null, "postcode": "TS1 1QD", "country": "GB", "eori_number": null }, "items": [ { "id": 26, "name": "Sandro Paris Checked Trench Coat", "url": "/product/sandro-paris-checked-trench-coat-4?variant=2", "sku": "SHPMA00148-M", "reference": null, "manufacturer": { "id": 2, "name": "Sandro Paris" }, "image": { "url": "http://l9.test/storage/images/products/uaaVbTbqbZxs1FH3N28Tw0a7dc6I7Xd08DiyPAG6.jpg" }, "product_id": 4, "variant_id": 14, "buyable_type": "variant", "buyable_id": 14, "shippable": true, "quantity": 2, "returned_quantity": 0, "price": { "amount": 42083.33, "tax": 8416.67 }, "discount": { "amount": 8416.67, "tax": 1683.33 }, "full_price": { "amount": 42083.33, "tax": 8416.67 }, "weight": 0, "volume": 0, "cost_price": { "amount": null, "currency": null }, "hs": null, "origin_country": null, "goods_description": null } ], "flags": [], "payments": [ { "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "method": { "id": 1, "name": "Cash", "driver": "cash" }, "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c", "state": "captured", "amount": 91000, "currency": "GBP", "captured_at": "2023-09-12T10:17:03.000000ZZ", "refunds": [ { "id": 1, "amount": 91000, "created_at": "2025-09-16T07:40:22.000000Z" } ] } ], "fulfillments": [], "returns": [ { "id": 1, "reason": "Test reason", "created_at": "2025-09-16T07:40:22.000000Z", "items": [ { "id": 28, "quantity": 2, "exchanged_for_id": null } ] } ], "comments": [] } ```