# 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..." } ```