General

• What are the available endpoints?
• What conventions does the API use?
• What responses does the API return?

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}

{
    "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

{
    "order": {
        "id": 15
    }
}

400 Bad Request

GET /api/orders/{id}

{
    "message": "Missing order ID"
}

401 Unauthorised

GET /api/orders/{id}

{
    "message": "Unauthorized: Bearer token missing."
}

404 Not Found

GET /api/orders/{id}

{
    "message": "The requested order with ID {id} could not be found."
}

422 Unprocessable Content

POST /api/orders

{
    "message": "The given data was invalid.",
    "errors": {
        "currency": ["The currency field is required."]
    }
}

500 Internal Server Error

{
    "message": "Exception message..."
}