{ "openapi": "3.1.0", "x-stoplight": { "id": "07dbd324ec273" }, "info": { "title": "API Overview", "version": "2026-07", "summary": "API Overview", "contact": { "name": "AfterShip Support", "url": "https://www.aftership.com/contact-us", "email": "support@aftership.com" }, "termsOfService": "https://www.aftership.com/legal/terms-of-service", "description": "> OAS Schema can be downloaded [here](https://stoplight.io/api/v1/projects/automizely/docs-api-automizely-com-commerce/nodes/reference/api.json?branch=testing%2F2026-07&deref=optimizedBundle)" }, "servers": [ { "url": "https://api.aftership.com/commerce/2026-07", "description": "API Endpoint" } ], "paths": { "/stores": { "post": { "summary": "Create a store", "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Store.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20100, "type": "Created", "message": "The request was successful, we created a new resource and the response body contains the representation." }, "data": { "id": "my-store-1", "created_at": "2024-05-06T12:32:00+01:00", "updated_at": "2024-05-06T12:32:00+01:00", "source_created_at": "2024-05-06T12:32:00+01:00", "source_updated_at": "2024-05-06T12:32:00+01:00", "platform": "aftership", "name": "My Store", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "support_email": "support@example.com", "weight_unit": "lb", "currency": "USD", "phone": "+11234567890", "address": { "street_1": "98 Circle", "street_2": "", "street_3": "", "city": "Daug City", "state": "New York", "country_region": "USA", "postal_code": "10001", "latitude": 43, "longitude": -75 }, "url": "https://www.exmaple.com", "description": "My shop", "categories": [ "shoes", "bags" ] } } } } } } } }, "operationId": "create-store", "description": "Create a new store.\n\n> **Important:** After creating a new store in Commerce API, please contact our support team to configure and enable the specific Commerce API features you need (such as `tracking`, `returns`, etc.) for this store. This configuration is separate from any AfterShip products you may have already subscribed to.
The returned `store.id` value is essential, as you'll need to include it in the header of all subsequent Commerce API requests as `as-store-id` to identify which store you're operating on.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "currency" ], "properties": { "id": { "type": "string", "description": "This ID will be used as the `as-store-id` header value when calling other resource endpoints.\n\nA custom identifier for the store. If not provided, the system will generate a UUID. Must be unique within the organization and immutable. \n\nCannot start with the reserved prefix `app-`. \n\nYou can use this ID to manage the resource in subsequent API calls. \n\nThis ID will be used as the `as-store-id` header value when calling other resource endpoints.", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "example": "my-store-1" }, "source_created_at": { "type": "string", "description": "Timestamp marking the creation of the store, formatted in [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2024-05-06T12:32:00+01:00" }, "source_updated_at": { "type": "string", "description": "The timestamp indicating the last update to the store, formatted in [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2024-05-06T12:32:00+01:00" }, "name": { "type": "string", "description": "The shop's name.", "maxLength": 256, "example": "My Store" }, "support_email": { "type": "string", "description": "Support email address for your store.", "maxLength": 256, "example": "support@example.com" }, "owner_email": { "type": "string", "description": "The email address of the store owner.", "maxLength": 256, "example": "store_owner@example.com" }, "timezone_identifier": { "type": "string", "description": "The name of the timezone of your store located, as defined by the [IANA timezone database standard](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "maxLength": 256, "default": "America/New_York" }, "weight_unit": { "type": "string", "description": "Unit of measurement for weight used by the store, such as \"lb\" or \"kg\"", "maxLength": 64, "example": "lb" }, "currency": { "type": "string", "description": "Indicates the currency used by the store. The currency should be specified using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) three-letter currency code (e.g., 'USD' for US Dollar, 'EUR' for Euro). ", "maxLength": 3, "example": "USD" }, "phone": { "type": "string", "description": "The store's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164).", "maxLength": 256, "example": "+11234567890" }, "url": { "type": "string", "description": "The URL of the store.", "maxLength": 2048, "example": "https://www.example.com" }, "description": { "type": "string", "description": "The text description of the store.", "maxLength": 10240, "example": "My shop" }, "categories": { "type": "array", "description": "The supported product category name of the store.", "maxItems": 100, "items": { "type": "string", "maxLength": 256 } }, "address": { "description": "The physical address of the store.", "type": "object", "properties": { "street_1": { "type": "string", "title": "The Street_1 Schema", "description": "First line of the store's street address.", "maxLength": 256 }, "street_2": { "type": "string", "title": "The Street_2 Schema", "description": "Second line of the store's street address.", "maxLength": 256 }, "street_3": { "type": "string", "title": "The Street_3 Schema", "description": "Third line of the store's street address.", "maxLength": 256 }, "city": { "type": "string", "title": "The City Schema", "description": "The city, town, or village where the store is located.", "maxLength": 256 }, "state": { "type": "string", "title": "The State Schema", "description": "Indicates the state or region where the store is located, such as a province, state, or prefecture.", "maxLength": 256 }, "postal_code": { "type": "string", "title": "The Postal_code Schema", "description": "The postal code of the store (also known as zip code, postcode, Eircode, etc.).", "maxLength": 256 }, "country_region": { "type": "string", "title": "The Country Schema", "description": "The store's country/region in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.", "example": "USA", "pattern": "^[A-Z]{3}$" }, "coordinate": { "type": "object", "description": "Store address coordinate.", "properties": { "longitude": { "type": "number", "description": "The longitude of the store address." }, "latitude": { "type": "number", "description": "The latitude of the store address." } } } } } } }, "examples": { "Example 1": { "value": { "id": "my-store-1", "source_created_at": "2024-05-06T12:32:00+01:00", "source_updated_at": "2024-05-06T12:32:00+01:00", "name": "My Store", "support_email": "support@example.com", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "weight_unit": "lb", "currency": "USD", "phone": "+11234567890", "url": "https://www.example.com", "description": "My shop", "categories": [ "shoes", "bags" ], "address": { "street_1": "98 Bofors Circle", "city": "New York", "state": "New York", "postal_code": "10001", "country_region": "USA", "coordinate": { "latitude": 40, "longitude": 74 } } } } } } }, "description": "" }, "tags": [ "Stores" ], "x-stoplight": { "id": "hadtz8qj5if6w" } }, "get": { "summary": "Get stores", "operationId": "get-stores", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "43pbqr696s1vw" } }, "data": { "type": "object", "x-stoplight": { "id": "i1m9d2a1owenx" }, "properties": { "stores": { "x-stoplight": { "id": "klhs7crx4ougd" }, "type": "array", "items": { "$ref": "#/components/schemas/Store.v1", "x-stoplight": { "id": "1gviwx15qjg0o" } } }, "pagination": { "$ref": "#/components/schemas/Pagination.v2", "x-stoplight": { "id": "gftlh15a2uix6" } }, "parameter_string": { "type": "string", "x-stoplight": { "id": "kflov9vr92k0c" }, "description": "A string that includes the request parameters.", "example": "page=1&limit=10" } } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "stores": [ { "id": "my-store-1", "created_at": "2024-05-06T12:32:00+01:00", "updated_at": "2024-05-06T12:32:00+01:00", "source_created_at": "2024-05-06T12:32:00+01:00", "source_updated_at": "2024-05-06T12:32:00+01:00", "platform": "aftership", "name": "My Store", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "support_email": "support@example.com", "weight_unit": "lb", "currency": "USD", "phone": "+11234567890", "address": { "street_1": "98 Circle", "street_2": "", "street_3": "", "city": "Daug City", "state": "New York", "country_region": "USA", "postal_code": "10001", "latitude": 43, "longitude": -75 }, "url": "https://www.exmaple.com", "description": "My shop", "categories": [ "shoes", "bags" ] } ], "pagination": { "page": 1, "limit": 10, "has_next_page": true }, "parameter_string": "page=1&limit=10" } } } } } } } }, "x-stoplight": { "id": "yc24p1srfyqiv" }, "description": "Get store results with multiple stores.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "limit", "description": "The maximum number of results to show on a page. Default is 10." }, { "schema": { "type": "string" }, "in": "query", "name": "page", "description": "Current page of the collection. Default is 1." }, { "schema": { "type": "string" }, "in": "query", "name": "ids[]", "description": "Each element must contain fewer than 128 characters. The total number of elements should not exceed 50. Each `id` should be used as an independent query parameter in the URL, as demonstrated in the following example: `GET /stores?ids[]=5247009653041&ids[]=5081836323059`" } ], "tags": [ "Stores" ] } }, "/stores/{id}": { "get": { "summary": "Get store by ID", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Store.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "my-store-1", "created_at": "2024-05-06T12:32:00+01:00", "updated_at": "2024-05-06T12:32:00+01:00", "source_created_at": "2024-05-06T12:32:00+01:00", "source_updated_at": "2024-05-06T12:32:00+01:00", "platform": "aftership", "name": "My Store", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "support_email": "support@example.com", "weight_unit": "lb", "currency": "USD", "phone": "+11234567890", "address": { "street_1": "98 Circle", "street_2": "", "street_3": "", "city": "Daug City", "state": "New York", "country_region": "USA", "postal_code": "10001", "latitude": 43, "longitude": -75 }, "url": "https://www.exmaple.com", "description": "My shop", "categories": [ "shoes", "bags" ] } } } } } } } }, "operationId": "get-store-by-id", "description": "Get a store by ID.", "parameters": [], "tags": [ "Stores" ], "x-stoplight": { "id": "kepefe38naajo" } }, "patch": { "summary": "Update store by ID", "operationId": "update-store-by-id", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Store.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "my-store-1", "created_at": "2024-05-06T12:32:00+01:00", "updated_at": "2024-05-06T12:32:00+01:00", "source_created_at": "2024-05-06T12:32:00+01:00", "source_updated_at": "2024-05-06T12:32:00+01:00", "platform": "aftership", "name": "My Store", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "support_email": "support@example.com", "weight_unit": "lb", "currency": "USD", "phone": "+11234567890", "address": { "street_1": "98 Circle", "street_2": "", "street_3": "", "city": "Daug City", "state": "New York", "country_region": "USA", "postal_code": "10001", "latitude": 43, "longitude": -75 }, "url": "https://www.exmaple.com", "description": "My shop", "categories": [ "shoes", "bags" ] } } } } } } } }, "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source_updated_at": { "type": "string", "description": "The timestamp indicating the last update to the store, formatted in [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2024-05-06T12:32:00+01:00" }, "name": { "type": "string", "description": "The shop's name.", "maxLength": 256, "example": "My Store" }, "support_email": { "type": "string", "description": "Support email address for your store.", "maxLength": 256, "example": "support@example.com" }, "owner_email": { "type": "string", "description": "The email address of the store owner.", "maxLength": 256, "example": "store_owner@example.com" }, "timezone_identifier": { "type": "string", "description": "The name of the timezone of your store located, as defined by the [IANA timezone database standard](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "maxLength": 256, "example": "America/New_York" }, "weight_unit": { "type": "string", "description": "Unit of measurement for weight used by the store, such as \"lb\" or \"kg\"", "maxLength": 64, "example": "lb" }, "phone": { "type": "string", "description": "The store's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164).", "maxLength": 256, "example": "+11234567890" }, "address": { "description": "The physical address of the store.", "type": "object", "properties": { "street_1": { "type": "string", "title": "The Street_1 Schema", "description": "First line of the store's street address.", "maxLength": 256 }, "street_2": { "type": "string", "title": "The Street_2 Schema", "description": "Second line of the store's street address.", "maxLength": 256 }, "street_3": { "type": "string", "title": "The Street_3 Schema", "description": "Third line of the store's street address.", "maxLength": 256 }, "city": { "type": "string", "title": "The City Schema", "description": "The city, town, or village where the store is located.", "maxLength": 256 }, "state": { "type": "string", "title": "The State Schema", "description": "Indicates the state or region where the store is located, such as a province, state, or prefecture.", "maxLength": 256 }, "postal_code": { "type": "string", "title": "The Postal_code Schema", "description": "The postal code of the store (also known as zip code, postcode, Eircode, etc.).", "maxLength": 256 }, "country_region": { "type": "string", "title": "The Country Schema", "description": "The store's country/region in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.", "example": "USA", "pattern": "^[A-Z]{3}$" }, "coordinate": { "type": "object", "description": "Store address coordinate.", "properties": { "longitude": { "type": "number", "description": "The longitude of the store address." }, "latitude": { "type": "number", "description": "The latitude of the store address." } } } } } } }, "examples": { "Example 1": { "value": { "source_updated_at": "2024-05-06T12:32:00+01:00", "name": "My Store", "support_email": "support@example.com", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "weight_unit": "lb", "phone": "+11234567890", "address": { "street_1": "98 Bofors Circle", "city": "New York", "state": "New York", "postal_code": "10001", "country_region": "USA", "coordinate": { "latitude": 40, "longitude": 74 } } } } } } } }, "description": "Update a store by ID.", "tags": [ "Stores" ], "x-stoplight": { "id": "7e8bomqsyg6ku" } }, "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the store." } ] }, "/locations": { "post": { "summary": "Create a location", "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Location.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20100, "type": "Created", "message": "The request was successful, we created a new resource and the response body contains the representation." }, "data": { "id": "warehouse_1", "name": "SF Warehouse", "source": "manual", "address": { "company": "AfterShip", "first_name": "John Doe", "last_name": "", "phone": "+14155551234", "email": "john@example.com", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-04-24T00:00:00Z" } } } } } } } }, "operationId": "create-location", "description": "Create a manual location. Locations created through Commerce API are organization-level resources and are not bound to a store. A custom `id` can be provided, but it cannot start with the reserved prefix `app-`.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "address" ], "properties": { "id": { "type": "string", "description": "A custom identifier for the location. If not provided, the system will generate a UUID. Must be unique within the organization and immutable. Cannot start with the reserved prefix `app-`.", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "example": "warehouse_1" }, "name": { "type": "string", "description": "The location name.", "maxLength": 256, "example": "SF Warehouse" }, "address": { "$ref": "#/components/schemas/Address_with_coordinate.v1", "description": "The physical address and contact information of the location. For Location resources, `first_name` and `last_name` are joined into one contact name on write; on read, the full contact name is returned as `first_name` and `last_name` is empty. The `type` field is accepted by the schema but not used for Location resources — omit it on write; on read it is always empty." }, "timezone_identifier": { "type": "string", "description": "The name of the timezone where the location is located, as defined by the [IANA timezone database standard](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "maxLength": 256, "example": "America/New_York" }, "opening_hours": { "$ref": "#/components/schemas/Opening_hours.v1", "description": "The regular opening hours of the location." }, "order_processing": { "type": "object", "additionalProperties": false, "description": "The order processing setting for this location. When `enabled` is `true`, `order_cutoff_time` and `order_processing_duration_days` are required.", "properties": { "enabled": { "type": "boolean", "description": "Whether order processing is enabled for this location.", "example": true }, "order_cutoff_time": { "type": "string", "description": "The daily cutoff time for processing orders in `HH:mm` format.", "example": "14:00" }, "order_processing_duration_days": { "type": "integer", "description": "The number of business days needed to process an order. Use `0` when fulfillment can be completed within 1 business day.", "minimum": 0, "example": 0 } } }, "pickup_setting": { "type": "object", "additionalProperties": false, "description": "The pickup setting for this location. When `enabled` is `true`, `order_processing_duration_seconds_min` and `order_processing_duration_seconds_max` are required.", "properties": { "enabled": { "type": "boolean", "description": "Whether pickup is enabled for this location.", "example": true }, "instructions": { "type": "string", "description": "Pickup instructions shown to the customer.", "maxLength": 2048, "example": "Please pick up at the front desk." }, "order_processing_duration_seconds_min": { "type": "integer", "description": "The minimum number of seconds needed before the order is ready for pickup.", "minimum": 0, "example": 3600 }, "order_processing_duration_seconds_max": { "type": "integer", "description": "The maximum number of seconds needed before the order is ready for pickup.", "minimum": 0, "example": 7200 } } } } }, "examples": { "Example 1": { "value": { "id": "warehouse_1", "name": "SF Warehouse", "address": { "company": "AfterShip", "first_name": "John", "last_name": "Doe", "phone": "+14155551234", "email": "john@example.com", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 } } } } } }, "description": "" }, "tags": [ "Locations" ], "x-stoplight": { "id": "create-location" } }, "get": { "summary": "Get locations", "operationId": "get-locations", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "type": "object", "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location.v1" } }, "pagination": { "$ref": "#/components/schemas/Pagination.v2" }, "parameter_string": { "type": "string", "description": "A string that includes the request parameters.", "example": "source=manual&page=1&limit=10" } } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "locations": [ { "id": "warehouse_1", "name": "SF Warehouse", "source": "manual", "address": { "company": "AfterShip", "first_name": "John Doe", "last_name": "", "phone": "+14155551234", "email": "john@example.com", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-04-24T00:00:00Z" } ], "pagination": { "page": 1, "limit": 10, "has_next_page": false }, "parameter_string": "source=manual&page=1&limit=10" } } } } } } } }, "description": "Get location results with multiple locations.", "parameters": [ { "schema": { "type": "string", "enum": [ "manual", "platform" ] }, "in": "query", "name": "source", "description": "Filter locations by source. `manual` means locations created through Commerce API. `platform` means locations imported from ecommerce platforms." }, { "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 200 }, "in": "query", "name": "page", "description": "Current page of the collection. Default is 1." }, { "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "description": "The maximum number of results to show on a page. Default is 10, maximum is 50." } ], "tags": [ "Locations" ], "x-stoplight": { "id": "get-locations" } } }, "/locations/{id}": { "get": { "summary": "Get location by ID", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Location.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "warehouse_1", "name": "SF Warehouse", "source": "manual", "address": { "company": "AfterShip", "first_name": "John Doe", "last_name": "", "phone": "+14155551234", "email": "john@example.com", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-04-24T00:00:00Z" } } } } } } } }, "operationId": "get-location-by-id", "description": "Get a location by ID. Use the `id` value returned in a `Location` resource response, such as from `GET /locations`, as this path parameter.", "parameters": [], "tags": [ "Locations" ], "x-stoplight": { "id": "get-location-by-id" } }, "patch": { "summary": "Update location by ID", "operationId": "update-location-by-id", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Location.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "warehouse_1", "name": "SF Warehouse", "source": "manual", "address": { "company": "AfterShip", "first_name": "John Doe", "last_name": "", "phone": "+14155551234", "email": "john@example.com", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-04-24T00:00:00Z" } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The location name. This field cannot be patched for platform-sourced locations.", "maxLength": 256, "example": "SF Warehouse" }, "address": { "type": "object", "additionalProperties": false, "description": "Patch the address and contact information of the location. The `address` object itself cannot be `null`; omit a field to keep its current value. For platform-sourced locations, only `email` and `phone` can be patched. For Location resources, `first_name` and `last_name` are joined into one contact name on write; on read, the full contact name is returned as `first_name` and `last_name` is empty. The `type` field is accepted by the schema but not used for Location resources — omit it on write; on read it is always empty.", "properties": { "company": { "type": "string", "description": "The name of the company associated to the address.", "maxLength": 256, "example": "AfterShip" }, "first_name": { "type": "string", "description": "The first name of the person associated to the address.", "maxLength": 256, "example": "John" }, "last_name": { "type": "string", "description": "The last name of the person associated to the address.", "maxLength": 256, "example": "Doe" }, "phone": { "type": "string", "description": "The phone number of the person associated to the address.", "maxLength": 256, "example": "+14155551234" }, "email": { "type": "string", "description": "The email address of the person associated to the address.", "maxLength": 256, "example": "john@example.com" }, "street_1": { "type": "string", "description": "First line of the street address.", "maxLength": 256, "example": "123 Main St" }, "street_2": { "type": "string", "description": "Second line of the street address.", "maxLength": 256, "example": "Suite 100" }, "street_3": { "type": "string", "description": "Third line of the street address.", "maxLength": 256, "example": "" }, "city": { "type": "string", "description": "The location's city, town, or village.", "maxLength": 256, "example": "San Francisco" }, "state": { "type": "string", "description": "The state or region of the location, such as a province, state, or prefecture.", "maxLength": 256, "example": "CA" }, "country_region": { "type": "string", "description": "The address country/region in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.", "pattern": "^[A-Z]{3}$", "example": "USA" }, "postal_code": { "type": "string", "description": "The postal code of the location.", "maxLength": 256, "example": "94105" }, "coordinate": { "type": "object", "additionalProperties": false, "description": "The coordinate of the address. If `coordinate` is provided, both `latitude` and `longitude` are required.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "description": "The latitude of the address.", "example": 37.7749 }, "longitude": { "type": "number", "description": "The longitude of the address.", "example": -122.4194 } } } } }, "timezone_identifier": { "type": "string", "description": "The name of the timezone where the location is located, as defined by the [IANA timezone database standard](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "maxLength": 256, "example": "America/New_York" }, "opening_hours": { "$ref": "#/components/schemas/Opening_hours.v1", "description": "Patch the regular opening hours of the location. The `opening_hours` object itself cannot be `null`. You may provide only the weekdays to update, but each provided weekday object is replaced atomically and must include `open`. When `open` is `false`, `from` and `to` must be `null` or omitted. When `open` is `true`, `from` and `to` must both be provided in `HH:mm` format or both be `null` for 24-hour operation." }, "order_processing": { "type": "object", "additionalProperties": false, "description": "Patch the order processing setting for this location. The `order_processing` object itself cannot be `null`. Omitted fields keep their current values. Sending only `enabled` toggles the setting without clearing `order_cutoff_time` or `order_processing_duration_days`; when enabling order processing, the final setting must include a valid cutoff time and processing duration.", "properties": { "enabled": { "type": "boolean", "description": "Whether order processing is enabled for this location.", "example": true }, "order_cutoff_time": { "type": "string", "description": "The daily cutoff time for processing orders in `HH:mm` format.", "example": "14:00" }, "order_processing_duration_days": { "type": "integer", "description": "The number of business days needed to process an order. Use `0` when fulfillment can be completed within 1 business day.", "minimum": 0, "example": 0 } } }, "pickup_setting": { "type": "object", "additionalProperties": false, "description": "Patch the pickup setting for this location. The `pickup_setting` object itself cannot be `null`. Omitted fields keep their current values. Sending only `enabled` toggles the setting without clearing existing pickup fields; when enabling pickup, the final setting must include valid minimum and maximum processing durations. This field cannot be patched for platform-sourced locations.", "properties": { "enabled": { "type": "boolean", "description": "Whether pickup is enabled for this location.", "example": true }, "instructions": { "type": "string", "description": "Pickup instructions shown to the customer.", "maxLength": 2048, "example": "Please pick up at the front desk." }, "order_processing_duration_seconds_min": { "type": "integer", "description": "The minimum number of seconds needed before the order is ready for pickup.", "minimum": 0, "example": 3600 }, "order_processing_duration_seconds_max": { "type": "integer", "description": "The maximum number of seconds needed before the order is ready for pickup.", "minimum": 0, "example": 7200 } } } } }, "examples": { "Example 1": { "value": { "address": { "city": "San Francisco" }, "timezone_identifier": "America/New_York", "opening_hours": { "monday": { "open": true, "from": "09:00", "to": "18:00" } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 } } } } } } }, "description": "Update a location by ID. Use the `id` value returned in a `Location` resource response, such as from `GET /locations`, as this path parameter. Omit a field to keep its current value. Top-level objects and scalar fields cannot be set to `null`. For platform-sourced locations, only `address.email`, `address.phone`, `timezone_identifier`, `opening_hours`, and `order_processing` can be patched; other fields are managed by the ecommerce platform.", "parameters": [], "tags": [ "Locations" ], "x-stoplight": { "id": "update-location-by-id" } }, "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "Location ID. Use the `id` value returned in a `Location` resource response, such as from `GET /locations`, as this path parameter." } ] }, "/products": { "post": { "summary": "Create a product", "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Product.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20100, "type": "Created", "message": "The request was successful, we created a new resource and the response body contains the representation." }, "data": { "id": "546735673", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "title": "Power Mobile Phone", "slug": "power-mobile-phone", "categories": [ "mobile-phone" ], "tags": [ "mobile-phone" ], "image_urls": [ "https://example.com/product/image.png" ], "url": "https://example.com/product/image.png", "published": true, "description": "string", "variants": [ { "id": "5634477687", "available_quantity": 1, "sku": "SKU001", "title": "Power Mobile Phone", "price": "10", "image_urls": [ "https://example.com/product/image.png" ], "compare_at_price": "string", "weight": { "unit": "kg", "value": 10 }, "allow_backorder": true, "options": [ { "name": "color", "value": "white" } ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-15T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-15T20:02:09Z" } } } } } } } }, "operationId": "create-product", "description": "Create a product.\n\n> If you receive an error message stating **\"Precondition failed, the store not found.\"**, please first create a store using the [Create a store](https://www.aftership.com/docs/commerce/2025-04/hadtz8qj5if6w-create-a-store) API.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "image_urls", "variants" ], "properties": { "id": { "type": "string", "description": "A custom identifier for the product. If not provided, the system will generate a UUID. Must be unique within the store and immutable. You can use this ID to manage the resource in subsequent API calls.", "maxLength": 128, "example": "my-custom-id-123", "pattern": "^[a-zA-Z0-9_-]+$" }, "title": { "type": "string", "description": "The title of the product.", "maxLength": 1024, "example": "Power Mobile Phone" }, "slug": { "type": "string", "description": "URL friendly unique identifier for the product.", "maxLength": 1024, "example": "power-mobile-phone" }, "categories": { "type": "array", "description": "The categories associated with the product, used for filtering and search purposes.", "maxItems": 100, "items": { "type": "string", "example": "mobile-phone" } }, "tags": { "type": "array", "description": "The tags associated with the product, used for filtering and search purposes.", "maxItems": 100, "items": { "type": "string", "example": "mobile-phone" } }, "image_urls": { "type": "array", "description": "URLs of the product images.", "maxItems": 100, "items": { "type": "string", "maxLength": 2048, "example": "https://example.com/product/image.png" } }, "url": { "type": "string", "description": "The URL of the product page in your online storefront.", "maxLength": 2048, "example": "https://example.com/product/" }, "published": { "type": "boolean", "description": "To indicate whether the product has been published.", "default": true }, "description": { "type": "string", "description": "Description of the product.", "maxLength": 10240 }, "variants": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "Product variant information.", "maxItems": 500, "items": { "$ref": "#/components/schemas/Product_variant.v1" } }, "source_created_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was created in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "source_updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was updated in your e-commerce system.", "example": "2021-04-15T20:02:09Z" } } }, "examples": { "Example 1": { "value": { "id": "546735673", "title": "Power Mobile Phone", "slug": "power-mobile-phone", "categories": [ "mobile-phone" ], "tags": [ "mobile-phone" ], "image_urls": [ "https://example.com/product/image.png" ], "url": "https://example.com/product/", "published": true, "description": "string", "variants": [ { "id": "5634477687", "available_quantity": 1, "sku": "string", "title": "Power Mobile Phone", "price": "10", "image_urls": [ "https://example.com/product/image.png" ], "compare_at_price": "string", "weight": { "unit": "kg", "value": 10 }, "allow_backorder": true, "options": [ { "name": "color", "value": "white" } ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-15T20:02:09Z" } } } } }, "description": "" }, "tags": [ "Products" ], "x-stoplight": { "id": "j3pzfhenf72sv" } }, "get": { "summary": "Get products", "operationId": "get-products", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "meta_object_id" } }, "data": { "type": "object", "x-stoplight": { "id": "data_object_id" }, "properties": { "products": { "type": "array", "x-stoplight": { "id": "products_array_id" }, "items": { "$ref": "#/components/schemas/Product.v1", "x-stoplight": { "id": "product_item_id" } } }, "pagination": { "$ref": "#/components/schemas/Pagination.v2", "x-stoplight": { "id": "pagination_object_id" } } } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "products": [ { "id": "product_id_1", "title": "Example Product 1", "slug": "example-product-1", "published": true }, { "id": "product_id_2", "title": "Example Product 2", "slug": "example-product-2", "published": false } ], "pagination": { "page": 1, "limit": 10, "has_next_page": true } } } } } } } } }, "description": "Get product results with multiple products.", "parameters": [ { "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 200 }, "in": "query", "name": "page", "description": "Page number" }, { "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "description": "Number of products per page" }, { "schema": { "type": "string", "items": { "type": "string" }, "maxItems": 50 }, "in": "query", "name": "ids[]", "description": "Array of product ID" }, { "schema": { "type": "string", "items": { "type": "string" }, "maxItems": 50 }, "in": "query", "name": "slugs[]", "description": "Array of product slug" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "description": "Search term (fuzzy search in title)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "published", "description": "Filter by published status" }, { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Products" ], "x-stoplight": { "id": "rloip27l58tm1" } } }, "/products/{id}": { "get": { "summary": "Get product by ID", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Product.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "546735673", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "title": "Power Mobile Phone", "slug": "power-mobile-phone", "categories": [ "mobile-phone" ], "tags": [ "mobile-phone" ], "image_urls": [ "https://example.com/product/image.png" ], "url": "https://example.com/product/image.png", "published": true, "description": "string", "variants": [ { "id": "5634477687", "available_quantity": 1, "sku": "SKU001", "title": "Power Mobile Phone", "price": "10", "image_urls": [ "https://example.com/product/image.png" ], "compare_at_price": "string", "weight": { "unit": "kg", "value": 10 }, "allow_backorder": true, "options": [ { "name": "color", "value": "white" } ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-15T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-15T20:02:09Z" } } } } } } } }, "operationId": "get-product-by-id", "description": "Get a product by id.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Products" ], "x-stoplight": { "id": "5pvl2tnkxwt0x" } }, "patch": { "summary": "Update product by ID", "operationId": "update-product-by-id", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Product.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "546735673", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "title": "Power Mobile Phone", "slug": "power-mobile-phone", "categories": [ "mobile-phone" ], "tags": [ "mobile-phone" ], "image_urls": [ "https://example.com/product/image.png" ], "url": "https://example.com/product/image.png", "published": true, "description": "string", "variants": [ { "id": "5634477687", "available_quantity": 1, "sku": "SKU001", "title": "Power Mobile Phone", "price": "10", "image_urls": [ "https://example.com/product/image.png" ], "compare_at_price": "string", "weight": { "unit": "kg", "value": 10 }, "allow_backorder": true, "options": [ { "name": "color", "value": "white" } ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-15T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-15T20:02:09Z" } } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "description": "Update product by ID.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the product.", "maxLength": 1024, "example": "Power Mobile Phone" }, "slug": { "type": "string", "description": "URL friendly unique identifier for the product.", "maxLength": 1024, "example": "power-mobile-phone" }, "categories": { "type": "array", "description": "The categories associated with the product, used for filtering and search purposes.", "maxItems": 100, "items": { "type": "string", "maxLength": 256, "example": "mobile-phone" } }, "tags": { "type": "array", "description": "The tags associated with the product, used for filtering and search purposes.", "maxItems": 100, "items": { "type": "string", "example": "mobile-phone" } }, "image_urls": { "type": "array", "description": "URLs of the product images.", "maxItems": 100, "items": { "type": "string", "maxLength": 2048, "example": "https://example.com/product/image.png" } }, "url": { "type": "string", "description": "The URL of the product page in your online storefront.", "maxLength": 2048, "example": "https://example.com/product/" }, "published": { "type": "boolean", "description": "To indicate whether the product has been published." }, "description": { "type": "string", "description": "Description of the product.", "maxLength": 10240 }, "source_updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was updated in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "variants": { "type": "array", "x-stoplight": { "id": "8pemo4er5lll6" }, "description": "Array of product variants. When provided, all existing variants will be replaced by this array. Any variants not included in the request will be deleted.", "items": { "$ref": "#/components/schemas/Product_variant.v1", "x-stoplight": { "id": "3adlhgb76quwh" } } } } }, "examples": { "Example 1": { "value": { "title": "Power Mobile Phone", "slug": "power-mobile-phone", "categories": [ "mobile-phone" ], "tags": [ "mobile-phone" ], "image_urls": [ "https://example.com/product/image.png" ], "url": "https://example.com/product/", "published": true, "description": "string", "source_updated_at": "2021-04-15T20:02:09Z" } } } } } }, "tags": [ "Products" ], "x-stoplight": { "id": "sk8tcmdv5qhz8" } }, "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the product." } ] }, "/products/{id}/variants": { "post": { "summary": "Create a new product variant", "description": "Create a new variant for the specified product. ", "tags": [ "Products" ], "operationId": "create-product-variant", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product_variant.v1" } } } }, "responses": { "201": { "description": "Variant created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "type": "object", "properties": { "variant": { "$ref": "#/components/schemas/Product_variant.v1" } } } } } } } } } } }, "/products/{id}/variants/{variant_id}": { "get": { "summary": "Get variant by ID", "description": "Get a specific variant of a product by its ID.", "tags": [ "Products" ], "operationId": "get-product-variant", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Product_variant.v1" } } } } } } } }, "patch": { "summary": "Update product variant", "description": "Update a specific variant of a product by its ID.", "tags": [ "Products" ], "operationId": "update-product-variant", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "available_quantity": { "type": "integer", "description": "Available quantity of the product variant.", "example": 1 }, "sku": { "type": "string", "description": "The product SKU of the product variant.", "maxLength": 1024, "example": "SKU001" }, "title": { "type": "string", "description": "The title of the product variant.", "maxLength": 1024, "example": "Power Mobile Phone" }, "price": { "type": "string", "description": "The price of the product variant.", "maxLength": 100, "example": "10" }, "image_urls": { "type": "array", "maxItems": 100, "description": "The product image URL of the product variant.", "items": { "type": "string", "maxLength": 1024, "example": "https://example.com/product/image.png" } }, "compare_at_price": { "type": "string", "description": "The original price of the item before an adjustment or a sale.", "maxLength": 100 }, "weight": { "$ref": "#/components/schemas/Weight.v1", "description": "The weight information of the product variant." }, "allow_backorder": { "type": "boolean", "description": "To specify whether customers are permitted to place an order for this out-of-stock product variant." }, "options": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "The custom product variant properties, such as size, color, and material.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The field name of the custom product property.", "maxLength": 256, "example": "color" }, "value": { "type": "string", "description": "The value of the custom product property.", "maxLength": 256, "example": "white" } } } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Product_variant.v1" } } } } } } } }, "delete": { "summary": "Delete product variant", "description": "Delete a specific variant of a product by its ID.", "tags": [ "Products" ], "operationId": "delete-product-variant", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Product_variant.v1" } } } } } } } } }, "/orders": { "post": { "summary": "Create an order", "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20100, "type": "Created", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "5187092316403", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "name": "#1086", "number": "1086", "currency": "HKD", "status": "open", "financial_status": "unpaid", "fulfillment_status": "unfulfilled", "order_total": "97", "shipping_total": "5", "tax_total": "10", "discount_total": "1", "subtotal": "90", "items": [ { "id": "13097711141107", "sku": "SKU001", "quantity": 1, "unit_weight": { "unit": "kg", "value": 10 }, "unit_price": { "currency": "USD", "amount": "10" }, "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone Pro", "discount": "10", "tax": "10", "product_id": "8021450916083", "product_variant_id": "43768285298931", "hs_code": "554521", "origin_country_region": "USA", "image_urls": [ "https://www.example.com/product/phone/image.jpg" ], "product_tags": [ "mobile-phone" ], "product_categories": [ "mobile-phone" ], "returnable_quantity": 1 } ], "note": "Created by AfterShip", "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "customer": { "id": "5127837778090", "first_name": "John", "last_name": "Doe", "emails": [ "john.doe@example.com" ], "locale": "en-US", "phones": [ "+11234567890" ] }, "shipping_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "billing_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "tags": [ "mobile-phone" ], "shipping_method": "standard shipping", "delivery_method": "shipping", "pickup_location": { "location_id": "string", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "pickup_info": { "instructions": "string", "estimated_ready_for_pickup_at": { "min": "2019-08-24T14:15:22Z", "max": "2019-08-24T14:15:22Z" }, "pickup_deadline_at": "2019-08-24T14:15:22Z" } } } } } } } } }, "operationId": "create-order", "description": "Create an order. \n\n> Please refer to the common scenario documentation for the usage of AfterShip Tracking, Shipping and Returns.\n\n> If you receive **41204 error (The store could not be found)**, please create a store with the [Create a store](https://www.aftership.com/docs/commerce/2025-04/hadtz8qj5if6w-create-a-store) endpoint before calling this API.\n\n\n
[url](../docs/common_scenarios/tracking/bopis.md)
", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Orders" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "currency", "number", "status", "order_total", "items", "delivery_method" ], "properties": { "id": { "type": "string", "description": "A custom identifier for the order. If not provided, the system will generate a UUID. Must be unique within the store and immutable. You can use this ID to manage the resource in subsequent API calls.", "maxLength": 128, "example": "my-custom-id-123", "pattern": "^[a-zA-Z0-9_-]+$", "x-stoplight": { "id": "mjrpj72to49gw" } }, "name": { "type": "string", "description": "The order name.", "maxLength": 256, "example": "#1086" }, "currency": { "type": [ "string" ], "description": "Specifies the currency for the order, adhering to the [ISO 4217 Currency Codes standard](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "pattern": "^[A-Z]{3}$" }, "number": { "type": "string", "description": "The order number.", "maxLength": 64, "example": "1086" }, "status": { "type": "string", "enum": [ "open", "closed", "canceled" ], "description": "The status of the order." }, "financial_status": { "type": [ "string", "null" ], "enum": [ "partially_paid", "paid", "partially_refunded", "refunded", "unpaid" ], "description": "The status of payments associated with the order. Defaults to `null` if not provided." }, "fulfillment_status": { "type": [ "string", "null" ], "enum": [ "unfulfilled", "partially_fulfilled", "fulfilled" ], "description": "The fulfillment status associated with the order. If not provided, this value is determined automatically. Since fulfillment has not been created at the time of order creation, it defaults to unfulfilled.\n\nIf you provide a value for this field when creating an order, you are responsible for updating the status manually from then onward. If you want AfterShip to manage the status automatically, do not provide this field when creating orders." }, "order_total": { "type": "string", "description": "Final amount paid by the customer, including of charges.\n\nFormula: \n`order_total = subtotal + shipping_total + tax_total`", "maxLength": 100, "example": "97" }, "subtotal": { "type": "string", "description": "Total after discounts, excluding taxes and shipping\n\nFormula: \n`subtotal = sum of all items' price`\n\n`1 item price = items.*.unit_price * items.*.quantity - items.*.discount`", "maxLength": 100, "example": "90" }, "shipping_total": { "type": "string", "description": "The total shipping fee applied to the price of the order.", "maxLength": 100, "example": "5" }, "tax_total": { "type": "string", "description": "The sum of all the taxes applied to the order.", "maxLength": 100, "example": "10" }, "discount_total": { "type": "string", "description": "The total discounts applied to the order. The value should be equal to the sum of all item discounts.", "maxLength": 100, "example": "1" }, "items": { "type": "array", "description": "Purchased items of the order.", "maxItems": 300, "minItems": 1, "items": { "$ref": "#/components/schemas/Order_item.v1" } }, "note": { "type": "string", "description": "A note that the shop owner can optionally attach to the order.", "maxLength": 5000, "example": "Created by AfterShip" }, "source_created_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was created in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "source_updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was updated in your e-commerce system.", "example": "2021-04-16T20:02:09Z" }, "customer": { "$ref": "#/components/schemas/Customer.v1", "description": "Customer information of the order." }, "shipping_address": { "$ref": "#/components/schemas/Address.v1", "description": "Shipping address of the order." }, "billing_address": { "$ref": "#/components/schemas/Address.v1", "description": "Billing address of the order." }, "tags": { "type": "array", "description": "Tags attached to the order.", "maxItems": 100, "items": { "type": "string", "example": "mobile-phone" } }, "shipping_method": { "type": "string", "description": "The name of the shipping method.", "maxLength": 256, "example": "standard shipping" }, "delivery_method": { "type": "string", "x-stoplight": { "id": "ewm9fia1h0hfj" }, "enum": [ "shipping", "pickup" ], "description": "Delivery method of the order.\n\nFor orders requiring shipping to buyers, please specify `shipping`. For Buy Online, Pick Up In Store (BOPIS) orders, please specify `pickup`.\n\nFor further details on pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../docs/common_scenarios/tracking/bopis.md).\n", "example": "shipping" }, "pickup_location": { "type": "object", "x-stoplight": { "id": "2oi1vnzlgtdc3" }, "description": "To indicate the pickup location of the order when the delivery method of the order is `pickup`.\n\nFor further details on pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../docs/common_scenarios/tracking/bopis.md).", "required": [ "location_id" ], "properties": { "location_id": { "type": "string", "x-stoplight": { "id": "s961j2vomx6rx" }, "description": "The unique identifier for the address. You can find or create the corresponding value [here](https://organization.automizely.com/warehouses).", "example": "b1cd63f641844a8e94208bad3c011ea3" } } }, "pickup_info": { "$ref": "#/components/schemas/Pickup.v1", "x-stoplight": { "id": "xuy8sphna6ej7" }, "description": "To indicate the detailed pickup instruction of the order when the delivery method of the order is `pickup`.\n\nFor further details on pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../docs/common_scenarios/tracking/bopis.md)." }, "status_timestamps": { "$ref": "#/components/schemas/Status_timestamps.v1", "x-stoplight": { "id": "8vvvtyweol0o1" } }, "custom_fields": { "$ref": "#/components/schemas/Order_custom_fields.v1", "x-stoplight": { "id": "ep64tykxqyu8q" } } } }, "examples": { "Example 1": { "value": { "id": "5187092316403", "name": "#1086", "number": "1086", "currency": "USD", "status": "open", "financial_status": "partially_paid", "fulfillment_status": "unfulfilled", "order_total": "97", "shipping_total": "5", "tax_total": "10", "discount_total": "1", "subtotal": "90", "items": [ { "id": "13097711141107", "sku": "SKU001", "quantity": 1, "unit_weight": { "unit": "kg", "value": 10 }, "unit_price": { "currency": "USD", "amount": "10" }, "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone Pro", "discount": "10", "tax": "10", "product_id": "8021450916083", "product_variant_id": "43768285298931", "hs_code": "554521", "origin_country_region": "USA", "image_urls": [ "https://www.example.com/product/phone/image.jpg" ], "product_tags": [ "mobile-phone" ], "product_categories": [ "mobile-phone" ], "returnable_quantity": 1 } ], "note": "Created by AfterShip", "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "customer": { "id": "5127837778090", "first_name": "John", "last_name": "Doe", "emails": [ "john.doe@example.com" ], "locale": "en-US", "phones": [ "+11234567890" ] }, "shipping_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "billing_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "tags": [ "mobile-phone" ], "shipping_method": "standard shipping", "delivery_method": "shipping", "pickup_location": { "location_id": "b1cd63f641844a8e94208bad3c011ea3" }, "pickup_info": { "instructions": "string", "estimated_ready_for_pickup_at": { "min": "2019-08-24T14:15:22Z", "max": "2019-08-24T14:15:22Z" }, "pickup_deadline_at": "2019-08-24T14:15:22Z" } } } } } } }, "x-stoplight": { "id": "hwj8tr3xn41rq" } }, "get": { "summary": "Get orders", "operationId": "get-orders", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "uhj872nkb4v0x" } }, "data": { "type": "object", "x-stoplight": { "id": "zfgwol14rqk1u" }, "properties": { "orders": { "type": "array", "x-stoplight": { "id": "e5ryg71wgv6j0" }, "minItems": 0, "maxItems": 50, "items": { "$ref": "#/components/schemas/Order.v1", "x-stoplight": { "id": "dw6s26g5cmgjt" } } }, "pagination": { "$ref": "#/components/schemas/Pagination.v2", "x-stoplight": { "id": "3uev4y3k91nv0" } }, "parameter_string": { "type": "string", "x-stoplight": { "id": "38ln8athl4tux" }, "description": "A string that includes the request parameters.", "example": "limit=10&page=1" } } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "orders": [ { "id": "5187092316403", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "name": "#1086", "number": "1086", "currency": "HKD", "status": "open", "financial_status": "unpaid", "fulfillment_status": "unfulfilled", "order_total": "97", "shipping_total": "5", "tax_total": "10", "discount_total": "1", "subtotal": "90", "items": [ { "id": "13097711141107", "sku": "SKU001", "quantity": 1, "unit_weight": { "unit": "kg", "value": 10 }, "unit_price": { "currency": "USD", "amount": "10" }, "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone Pro", "discount": "10", "tax": "10", "product_id": "8021450916083", "product_variant_id": "43768285298931", "hs_code": "554521", "origin_country_region": "USA", "image_urls": [ "https://www.example.com/product/phone/image.jpg" ], "product_tags": [ "mobile-phone" ], "product_categories": [ "mobile-phone" ], "returnable_quantity": 1 } ], "note": "Created by AfterShip", "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "customer": { "id": "5127837778090", "first_name": "John", "last_name": "Doe", "emails": [ "john.doe@example.com" ], "locale": "en-US", "phones": [ "+11234567890" ] }, "shipping_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "billing_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "tags": [ "mobile-phone" ], "shipping_method": "standard shipping", "delivery_method": "shipping", "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } ], "pagination": { "page": 0, "limit": 0, "has_next_page": true }, "parameter_string": "limit=10&page=1" } } } } } } } }, "x-stoplight": { "id": "kr3dy6e5ma49n" }, "description": "Get order results with multiple orders.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ids[]", "description": "Each element should be less than 128 characters. Count of the elements should be less than 50. Every id should be used as an independent query param, as the following url example shows: /orders?ids[]=5247009653041&ids[]=5081836323059 " }, { "schema": { "type": "integer", "maximum": 50, "minimum": 1 }, "in": "query", "name": "limit", "description": "The maximum number of results to show on a page. Default is 10." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "page", "description": "Current page of the collection. Default is 1." }, { "schema": { "type": "string", "enum": [ "-source_created_at", "+source_created_at", "-source_updated_at", "+source_updated_at" ], "example": "-source_created_at" }, "in": "query", "name": "sort", "description": "Sort the results list by the given value. Default is '-source_created_at' ." }, { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Orders" ] } }, "/orders/{id}": { "get": { "summary": "Get order by ID", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order.v1" } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "5187092316403", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "name": "#1086", "number": "1086", "currency": "HKD", "status": "open", "financial_status": "unpaid", "fulfillment_status": "unfulfilled", "order_total": "97", "shipping_total": "5", "tax_total": "10", "discount_total": "1", "subtotal": "90", "items": [ { "id": "13097711141107", "sku": "SKU001", "quantity": 1, "unit_weight": { "unit": "kg", "value": 10 }, "unit_price": { "currency": "USD", "amount": "10" }, "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone Pro", "discount": "10", "tax": "10", "product_id": "8021450916083", "product_variant_id": "43768285298931", "hs_code": "554521", "origin_country_region": "USA", "image_urls": [ "https://www.example.com/product/phone/image.jpg" ], "product_tags": [ "mobile-phone" ], "product_categories": [ "mobile-phone" ], "returnable_quantity": 1 } ], "note": "Created by AfterShip", "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "customer": { "id": "5127837778090", "first_name": "John", "last_name": "Doe", "emails": [ "john.doe@example.com" ], "locale": "en-US", "phones": [ "+11234567890" ] }, "shipping_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "billing_address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" }, "tags": [ "mobile-phone" ], "shipping_method": "standard shipping", "delivery_method": "shipping", "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } } } } } } } }, "operationId": "get-order-by-id", "description": "Get an order by ID.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Orders" ], "x-stoplight": { "id": "egf6ns3d62ie7" } }, "patch": { "summary": "Update order by ID", "operationId": "update-order-by-id", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order.v1" } } }, "examples": { "Response Example": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by Automizely." }, "data": { "id": "3712367526058", "store": { "id": "0ecb8ff7efa84d7d8f763ed7b21851d1" }, "number": "1002", "name": "#1002", "currency": "USD", "status": "closed", "delivery_method": "shipping", "financial_status": "paid", "fulfillment_status": "fulfilled", "shipping_method": "Free Shipping", "order_total": "9", "shipping_total": "0", "tax_total": "0", "discount_total": "1", "subtotal": "10", "items": [ { "id": "9716591689898", "sku": "", "title": "iPhone pro max", "product_variant_title": "iPhone pro max Red", "quantity": 1, "unit_weight": { "unit": "g", "value": 1 }, "product_tags": [ "Discounted" ], "product_categories": [ "Pants" ], "image_urls": [ "https://google.com/xxx.png" ], "unit_price": { "currency": "USD", "amount": "5" }, "discount": "0.5", "tax": "0", "product_id": "6582419718314", "product_variant_id": "39468493078698", "hs_code": "1", "origin_country_region": "USA" } ], "note": "test", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-26T13:42:19Z", "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-26T13:42:19Z", "customer": { "id": "5127837778090", "first_name": "John", "last_name": "Doe", "emails": [ "john.doe@example.com" ], "phones": [ "+11234567890" ], "locale": "fr-FR" }, "shipping_address": { "company": "AS", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "street_1": "40 level", "street_2": "Das tower", "street_3": "", "city": "SHENZHEN", "state": "Alabama", "country_region": "CHN", "postal_code": "59390", "phone": "+11234567890", "type": "business" }, "billing_address": { "company": "AS", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "street_1": "40 level", "street_2": "Das tower", "street_3": "", "city": "SHENZHEN", "state": "Alabama", "country_region": "CHN", "postal_code": "59390", "phone": "+11234567890", "type": "business" }, "tags": [] } } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "A note that the shop owner can optionally attach to the order.", "maxLength": 5000, "example": "created by AfterShip" }, "source_updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was updated in your e-commerce system.", "example": "2021-04-16T20:02:09Z" }, "customer": { "$ref": "#/components/schemas/Customer.v1", "description": "Customer information of the order." }, "shipping_address": { "$ref": "#/components/schemas/Address.v1", "description": "Shipping address of the order." }, "billing_address": { "$ref": "#/components/schemas/Address.v1", "description": "Billing address of the order." }, "tags": { "type": "array", "description": "Tags attached to the order.", "maxItems": 100, "items": { "type": "string", "example": "this is a tag" } }, "status": { "type": "string", "enum": [ "open", "closed", "canceled" ], "description": "The status of this order." }, "financial_status": { "type": [ "string", "null" ], "enum": [ "unpaid", "partially_paid", "paid", "partially_refunded", "refunded" ], "description": "The status of payments associated with the order." }, "fulfillment_status": { "type": [ "string", "null" ], "enum": [ "unfulfilled", "partially_fulfilled", "fulfilled" ], "description": "The status of fulfillment associated with the order." }, "status_timestamps": { "$ref": "#/components/schemas/Status_timestamps.v1", "x-stoplight": { "id": "orh4bj01er23a" } }, "custom_fields": { "$ref": "#/components/schemas/Order_custom_fields.v1", "x-stoplight": { "id": "6zx6j1tzyj7uz" } }, "currency": { "type": "string", "x-stoplight": { "id": "aq0fyvfm7zzse" }, "description": "Specifies the currency for the order, adhering to the ISO 4217 Currency Codes standard" }, "order_total": { "type": "string", "x-stoplight": { "id": "xcjiik389th6n" }, "description": "The total price of the order." }, "shipping_total": { "type": "string", "x-stoplight": { "id": "nhajinwtm1j3x" }, "description": "The total shipping fee applied to the price of the order." }, "tax_total": { "type": "string", "x-stoplight": { "id": "8h0lmbuekdz93" }, "description": "The sum of all the taxes applied to the order." }, "discount_total": { "type": "string", "x-stoplight": { "id": "7sg2agrvxuiqp" }, "description": "The total discounts applied to the order. The value should be equal to the sum of all item discounts." }, "subtotal": { "type": "string", "x-stoplight": { "id": "jf60g3gi201qo" }, "description": "The price of the order after discounts but before shipping and taxes." } } } } }, "description": "" }, "tags": [ "Orders" ], "description": "Update an order by ID.", "x-stoplight": { "id": "4mq75615nodwt" } }, "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the order." } ] }, "/orders/{id}/items": { "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the order." } ], "post": { "summary": "Create an order item", "operationId": "create-order-item", "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order_item.v1" } } } } } } }, "description": "Create a new order item.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order_item.v1" } } } }, "tags": [ "Orders" ] } }, "/orders/{id}/items/{item_id}": { "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the order." }, { "schema": { "type": "string" }, "name": "item_id", "in": "path", "required": true, "description": "The ID of the order item." } ], "get": { "summary": "Get order item by ID", "operationId": "get-order-item", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order_item.v1" } } } } } } }, "description": "Get an order item by ID.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Orders" ] }, "patch": { "summary": "Update order item by ID", "operationId": "update-order-item", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order_item.v1" } } } } } } }, "description": "Update an order item by ID.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product in your system.", "maxLength": 128 }, "product_variant_id": { "type": "string", "description": "The ID of the product variant in your system.", "maxLength": 128 }, "product_title": { "type": "string", "description": "The title of the product.", "maxLength": 1024 }, "product_variant_title": { "type": "string", "description": "The title of the product variant.", "maxLength": 1024 }, "sku": { "type": "string", "description": "The SKU of the product variant.", "maxLength": 256 }, "quantity": { "type": "integer", "description": "The quantity of the item ordered." }, "unit_price": { "$ref": "#/components/schemas/Money.v1", "description": "The unit price of the item." }, "unit_weight": { "$ref": "#/components/schemas/Weight.v1", "description": "The unit weight of the item." }, "image_urls": { "type": "array", "description": "URLs of the product images.", "items": { "type": "string", "maxLength": 2048 } }, "discount": { "type": "string", "x-stoplight": { "id": "c8pl97bvku8ae" }, "description": "The total amount of the discount allocated to the line item. Including the discount applied only on this item and the allocated discount for the order level discount." }, "tax": { "type": "string", "x-stoplight": { "id": "0e2edj72pue93" }, "description": "The total amount of the tax allocated to the line item." }, "hs_code": { "type": "string", "x-stoplight": { "id": "8pzm6gt743ogt" }, "description": "Harmonized System (HS) Codes." }, "origin_country_region": { "type": "string", "x-stoplight": { "id": "27f5ws0pye8jo" }, "description": "The origin country of this product. The field should in ISO 3166-1 alpha-3 format." }, "product_tags": { "type": "array", "x-stoplight": { "id": "9hf3yn280b66v" }, "description": "Product tags of this variant.", "items": { "x-stoplight": { "id": "5izqgoiatrxct" }, "type": "string" } }, "product_categories": { "type": "array", "x-stoplight": { "id": "8tsdhyi8tkmcd" }, "description": "Product categories of this variant.", "items": { "x-stoplight": { "id": "046g4zolxw34q" }, "type": "string" } }, "returnable_quantity": { "type": "integer", "x-stoplight": { "id": "gwnhna37rfhge" }, "description": "This field allows you to set the maximum returnable quantity for an order item when importing the order. When a shopper requests a return, they will not be able to select a quantity exceeding this specified limit." } } } } } }, "tags": [ "Orders" ] }, "delete": { "summary": "Delete an order item", "operationId": "delete-order-item", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1" }, "data": { "$ref": "#/components/schemas/Order_item.v1" } } } } } } }, "description": "Delete an order item by ID.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Orders" ] } }, "/fulfillments": { "parameters": [], "post": { "summary": "Create a fulfillment", "operationId": "create-fulfillment", "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "ujkfz8gihsdst" } }, "data": { "$ref": "#/components/schemas/Fulfillment.v1", "x-stoplight": { "id": "qnklgttqrn1fg" } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "423562565", "order_id": "5187092316403", "delivery_method": "pickup", "status": "processing", "line_items": [ { "id": "13097711141107", "product_id": "8021450916083", "product_variant_id": "43768285298931", "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone (While)", "sku": "SKU001", "quantity": 1, "unit_price": { "currency": "USD", "amount": "10" }, "unit_weight": { "unit": "kg", "value": 10 }, "image_urls": [ "https://example.com/product/image.png" ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "ship_from_location": { "location_id": "489b4bdec18d45d387752d63fb51ee1d", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" } }, "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "trackings": [ { "tracking_number": "RA123456789US", "slug": "usps", "service_type": "standard shipping", "ship_date": "2023-05-04", "custom_fields": {}, "next_couriers": [ { "tracking_number": "RA123456789US", "slug": "usps" } ] } ], "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "order_id", "delivery_method", "status", "line_items" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "2mukldoy9aah7" }, "description": "A custom identifier for the fulfillment. If not provided, the system will generate a UUID. Must be unique within the store and immutable. You can use this ID to manage the resource in subsequent API calls.", "maxLength": 128, "example": "my-custom-id-123", "pattern": "^[a-zA-Z0-9_-]+$" }, "order_id": { "type": "string", "description": "The unique identifier of the order. This value must match the id of the order as returned by the GET /orders or GET /orders/{id} endpoints in the current API version.", "example": "960d25e570834e84b2a0fffd08fab7f9" }, "delivery_method": { "type": "string", "enum": [ "pickup", "shipping" ], "x-stoplight": { "id": "afqvk957zyot8" }, "description": "Delivery method of the order. For BOPIS related feature, please specify `pickup`.\n\nFor more information about pickup order, please check the detailed [BOPIS introduction page](../docs/common_scenarios/tracking/bopis.md).\n", "example": "shipping" }, "status": { "type": "string", "description": "The status of the fulfillment. Depending of on the `delivery_method`, the allowed values are different.\n\nAllowed values: \n\ndelivery_method is shipping:\n`pending`, `processing`, `shipped`, `canceled`, and the custom defined statuses.\n\ndelivery_method is pickup:\n`pending`, `processing`, `ready_for_pickup`, `picked_up`, `canceled`, and the custom defined statuses.", "example": "pending" }, "line_items": { "type": "array", "description": "The items which included in this fulifllment.", "items": { "type": "object", "required": [ "id", "quantity" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "b8ylued052ce5" }, "description": "A unique identifier for the line item in your system. The value should be exist in one of the items in the corresponding order.\n\nNote that it should be the same as the `order.items.*.id` of the `Order` resource.\n\n", "example": "365756526" }, "quantity": { "type": "integer", "description": "The number of items in this fulfillment.", "example": 1 } } } }, "source_created_at": { "type": "string", "format": "date-time", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the fulfillment was created in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "source_updated_at": { "type": "string", "format": "date-time", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the fulfillment was updated in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "ship_from_location": { "type": "object", "description": "The location information where the fulfillment shipped from. It is recommended to include this field if the fulfillment's delivery method is `shipping`. Note that you must provide either `location_id` or `address`, but not both.", "additionalProperties": false, "properties": { "location_id": { "type": "string", "description": "The unique identifier for the location, as provided by AfterShip. You can manage and configure these locations [here](https://organization.automizely.com/warehouses).", "example": "489b4bdec18d45d387752d63fb51ee1d" }, "address": { "$ref": "#/components/schemas/Address.v1", "description": "The address object of this location." } } }, "pickup_location": { "type": "object", "description": "The location information where the fulfillment is designated to be pickup from. Mandatory when the delivery method of the fulfillment is `pickup`.", "required": [ "location_id" ], "properties": { "location_id": { "type": "string", "x-stoplight": { "id": "oeu555x37j99n" }, "description": "The ID of the Location pre-created in AfterShip admin", "example": "a52eeb761d204f3cbae06fa93b452976" } } }, "trackings": { "type": "array", "description": "Represents shipment tracking information. This object supports two mutually exclusive usage patterns:\n\nReference Mode: Pass the id of a resource pre-created via the Tracking API. This enables full tracking capabilities.\n\nInline Mode: Pass the tracking_number (and optional slug) directly. This is strictly for record-keeping purposes and does not create an active tracking task or support status updates.", "items": { "$ref": "#/components/schemas/Tracking.v1" } }, "pickup_info": { "$ref": "#/components/schemas/Pickup.v1", "x-stoplight": { "id": "5aa9r2fwkttmx" }, "description": "The pickup information of the fulfillment. It is recommended to include this field if the fulfillment's delivery method is `pickup`." } } }, "examples": { "Example 1": { "value": { "id": "25462567654", "delivery_method": "pickup", "status": "pending", "line_items": [ { "id": "365756526", "quantity": 1 } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-15T20:02:09Z", "ship_from_location": { "location_id": "a2a00a8bfefb423a98f456c95dfbfde5" }, "pickup_location": { "location_id": "a52eeb761d204f3cbae06fa93b452976" }, "trackings": [ { "id": "tracking1" }, { "id": "tracking2" } ], "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Fulfillments" ], "description": "Create a fulfillment.\n\n
[url](../docs/common_scenarios/tracking/bopis.md)
" }, "get": { "summary": "Get fulfillments", "operationId": "get-fulfillments", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "2oof1vzbg6pbc" } }, "data": { "type": "object", "x-stoplight": { "id": "afcxh5cs1luoe" }, "properties": { "fulfillments": { "type": "array", "x-stoplight": { "id": "gnkg1y38ly9wx" }, "items": { "$ref": "#/components/schemas/Fulfillment.v1", "x-stoplight": { "id": "61k82pdpp1a41" } } }, "pagination": { "$ref": "#/components/schemas/Pagination.v2", "x-stoplight": { "id": "nw7cd7995yweq" } } } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "fulfillments": [ { "id": "423562565", "order_id": "5187092316403", "delivery_method": "pickup", "status": "processing", "line_items": [ { "id": "13097711141107", "product_id": "8021450916083", "product_variant_id": "43768285298931", "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone (While)", "sku": "SKU001", "quantity": 1, "unit_price": { "currency": "USD", "amount": "10" }, "unit_weight": { "unit": "kg", "value": 10 }, "image_urls": [ "https://example.com/product/image.png" ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "ship_from_location": { "location_id": "489b4bdec18d45d387752d63fb51ee1d", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" } }, "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "trackings": [ { "tracking_number": "RA123456789US", "slug": "usps", "service_type": "standard shipping", "ship_date": "2023-05-04", "custom_fields": {}, "next_couriers": [ { "tracking_number": "RA123456789US", "slug": "usps" } ] } ], "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } ], "pagination": { "page": 0, "limit": 0, "has_next_page": true } } } } } } } } }, "description": "Get fulfillment results with multiple fulfillments.\n\n> In the query parameters, you must include only one of the following: `order_id` or `ids[]`. All other parameters should be omitted.

Only a single filter parameter can be included in each request.\n\n\n\n", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "order_id", "description": "Order ID" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 20 }, "in": "query", "name": "ids[]", "description": "Fulfillment IDs. Max length is 20" }, { "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit" }, { "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 200 }, "in": "query", "name": "page" }, { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Fulfillments" ] } }, "/fulfillments/{id}": { "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the fulfillment." } ], "get": { "summary": "Get fulfillment by ID", "operationId": "get-fulfillment-by-id", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "tyd6pnlqdafgi" } }, "data": { "$ref": "#/components/schemas/Fulfillment.v1", "x-stoplight": { "id": "k1rdsmaa4a69n" } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "423562565", "order_id": "5187092316403", "delivery_method": "pickup", "status": "processing", "line_items": [ { "id": "13097711141107", "product_id": "8021450916083", "product_variant_id": "43768285298931", "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone (While)", "sku": "SKU001", "quantity": 1, "unit_price": { "currency": "USD", "amount": "10" }, "unit_weight": { "unit": "kg", "value": 10 }, "image_urls": [ "https://example.com/product/image.png" ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "ship_from_location": { "location_id": "489b4bdec18d45d387752d63fb51ee1d", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" } }, "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "trackings": [ { "tracking_number": "RA123456789US", "slug": "usps", "service_type": "standard shipping", "ship_date": "2023-05-04", "custom_fields": {}, "next_couriers": [ { "tracking_number": "RA123456789US", "slug": "usps" } ] } ], "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Fulfillments" ], "description": "Get a fulfillment by ID." }, "patch": { "summary": "Update fulfillment by ID", "operationId": "update-fulfillment-by-id", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "4qrgu8l1wtgk0" } }, "data": { "$ref": "#/components/schemas/Fulfillment.v1", "x-stoplight": { "id": "xkfjdnmq8lb1g" } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "423562565", "order_id": "5187092316403", "delivery_method": "pickup", "status": "processing", "line_items": [ { "id": "13097711141107", "product_id": "8021450916083", "product_variant_id": "43768285298931", "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone (While)", "sku": "SKU001", "quantity": 1, "unit_price": { "currency": "USD", "amount": "10" }, "unit_weight": { "unit": "kg", "value": 10 }, "image_urls": [ "https://example.com/product/image.png" ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "ship_from_location": { "location_id": "489b4bdec18d45d387752d63fb51ee1d", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" } }, "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "trackings": [ { "tracking_number": "RA123456789US", "slug": "usps", "service_type": "standard shipping", "ship_date": "2023-05-04", "custom_fields": {}, "next_couriers": [ { "tracking_number": "RA123456789US", "slug": "usps" } ] } ], "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source_updated_at": { "type": "string", "x-stoplight": { "id": "e2qmaz5g0y1f9" }, "example": "2021-04-15T20:02:09Z", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the fulfillment was updated in your e-commerce system." }, "pickup_info": { "$ref": "#/components/schemas/Pickup.v1", "x-stoplight": { "id": "62dp4m5z4n5ox" }, "description": "The pickup information of the fulfillment. It is recommended to include this field if the fulfillment's delivery method is `pickup`." }, "trackings": { "type": "array", "x-stoplight": { "id": "jlthskrdds0zx" }, "description": "The shipment information of the fulfillment. **Note**: This endpoint directly replaces any existing trackings with the provided data. To avoid updating trackings, simply omit this key-value pair from your request. Note that providing an empty array will result in the deletion of all current trackings.", "items": { "$ref": "#/components/schemas/Tracking.v1", "x-stoplight": { "id": "cjkv26yzl5jcb" } } }, "ship_from_location": { "type": "object", "x-stoplight": { "id": "t5xw5npcu6vxj" }, "description": "The location information where the fulfillment shipped from. It is recommended to include this field if the fulfillment's delivery method is `shipping`.", "additionalProperties": false, "properties": { "location_id": { "type": "string", "description": "The unique identifier for the location, as provided by AfterShip. You can manage and configure these locations [here](https://organization.automizely.com/warehouses).", "example": "489b4bdec18d45d387752d63fb51ee1d" }, "address": { "$ref": "#/components/schemas/Address.v1", "description": "The address object of this location." } } }, "pickup_location": { "$ref": "#/components/schemas/Pickup_location.v1", "x-stoplight": { "id": "ou78lfdhqjx26" }, "description": "The location information where the fulfillment is designated to be pickup from. Mandatory when the delivery method of the fulfillment is `pickup`." } } }, "examples": { "Example 1": { "value": { "source_updated_at": "2021-04-15T20:02:09Z", "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" }, "trackings": [ { "tracking_number": "RA123456789US", "slug": "usps", "service_type": "standard shipping", "ship_date": "2023-05-04", "custom_fields": {}, "next_couriers": [ { "tracking_number": "RA123456789US", "slug": "usps" } ] } ], "ship_from_location": { "location_id": "489b4bdec18d45d387752d63fb51ee1d", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" } }, "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } } } } } } } }, "description": "Update a fulfillment by ID.", "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Fulfillments" ] } }, "/fulfillments/{id}/update-status": { "parameters": [ { "schema": { "type": "string" }, "name": "id", "in": "path", "required": true, "description": "The ID of the fulfillment." } ], "post": { "summary": "Update fulfillment status", "operationId": "update-fulfillment-status", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/Meta.v1", "x-stoplight": { "id": "jymi39zdlju1g" } }, "data": { "$ref": "#/components/schemas/Fulfillment.v1", "x-stoplight": { "id": "b4h6snhjfycm1" } } } }, "examples": { "Example 1": { "value": { "meta": { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." }, "data": { "id": "423562565", "order_id": "5187092316403", "delivery_method": "pickup", "status": "processing", "line_items": [ { "id": "13097711141107", "product_id": "8021450916083", "product_variant_id": "43768285298931", "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone (While)", "sku": "SKU001", "quantity": 1, "unit_price": { "currency": "USD", "amount": "10" }, "unit_weight": { "unit": "kg", "value": 10 }, "image_urls": [ "https://example.com/product/image.png" ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-16T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-16T20:02:09Z", "ship_from_location": { "location_id": "489b4bdec18d45d387752d63fb51ee1d", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890" } }, "pickup_location": { "location_id": "e9ec84ff351e45e089a7b75ae497e1ae", "address": { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": "", "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+11234567890", "coordinate": { "latitude": 43, "longitude": -75 } }, "opening_hours": { "sunday": { "open": true, "from": "10:30", "to": "20:30" }, "monday": { "open": true, "from": "10:30", "to": "20:30" }, "tuesday": { "open": true, "from": "10:30", "to": "20:30" }, "wednesday": { "open": true, "from": "10:30", "to": "20:30" }, "thursday": { "open": true, "from": "10:30", "to": "20:30" }, "friday": { "open": true, "from": "10:30", "to": "20:30" }, "saturday": { "open": true, "from": "10:30", "to": "20:30" } } }, "trackings": [ { "tracking_number": "RA123456789US", "slug": "usps", "service_type": "standard shipping", "ship_date": "2023-05-04", "custom_fields": {}, "next_couriers": [ { "tracking_number": "RA123456789US", "slug": "usps" } ] } ], "pickup_info": { "instructions": "Shop open from Mon to Fri", "estimated_ready_for_pickup_at": { "min": "2021-04-15T20:02:09Z", "max": "2021-04-15T20:02:09Z" }, "pickup_deadline_at": "2021-04-15T20:02:09Z" } } } } } } } } }, "description": "Updating the fulfillment status by fulfillment ID.\n\n## Status Updating Sequence\n\nThe fulfillment status must be updated in a specific sequence according to the fullfilment delivery method (`fulfillment.delivery_method`).\n\nFor `shipping` fulfillment, the statuses should be updated in the following order:\n\n> `pending` → `processing` → `shipped` → `canceled`\n\n**Note:** Updating the status in reverse, such as updating from `shipped` to `processing`, **is not permitted**.\n\nSimilarly, for `pickup` fulfillment, the statuses should be updated in the following order:\n\n> `pending` → `processing` → `ready_for_pickup` → `picked_up` → `canceled`\n\n## Custom Status\n\nThe provided status sequences do not include any custom statuses. For custom statuses, please adhere to the sequence configured in the AfterShip Admin Portal.\n\nEnsure that statuses are updated in the prescribed order to avoid any discrepancies.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "status": "custom-status" } }, "required": [ "status", "occurred_at" ], "properties": { "status": { "type": "string", "x-stoplight": { "id": "caaaa22j8prpm" }, "description": "The status of the fulfillment. Depending of on the `delivery_method`, the allowed values are different.\n\nAllowed values: \n\ndelivery_method is shipping:\n`pending`, `processing`, `shipped`, `canceled`, and the custom defined statuses.\n\ndelivery_method is pickup:\n`pending`, `processing`, `ready_for_pickup`, `picked_up`, `canceled`, and the custom defined statuses.", "example": "pending" }, "occurred_at": { "type": "string", "x-stoplight": { "id": "mgkf5gceepa4k" }, "format": "date-time", "description": "Indicates the time the status was updated, showing when the Doege occurred for the fulfillment, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2021-04-15T20:02:09Z" } } }, "examples": { "Example 1": { "value": { "status": "pending", "occurred_at": "2021-04-15T20:02:09Z" } } } } }, "description": "" }, "x-internal": false, "parameters": [ { "$ref": "#/components/parameters/as-store-id" } ], "tags": [ "Fulfillments" ] } } }, "tags": [ { "name": "Stores" }, { "name": "Locations" }, { "name": "Products" }, { "name": "Orders" }, { "name": "Fulfillments" } ], "components": { "securitySchemes": { "as-api-key": { "name": "as-api-key", "type": "apiKey", "in": "header" } }, "parameters": { "as-store-id": { "name": "as-store-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "This value equals to `store.id` of `Store` Resource. You can obtain this id by making a GET /stores call to get existing stores or a POST /stores to create a new store." } }, "schemas": { "Error.v1": { "type": "object", "title": "Error", "description": "The `Error` model contains a \"path\" key and an \"info\" key. The \"path\" is the JSON path of the request object to indicate the error location. The \"info\" is a human-readable description of the error.", "examples": [ { "path": "data.policy_id", "info": "data.policy_id must not be 32 characters" } ], "additionalProperties": false, "x-tags": [ "Envelope" ], "properties": { "path": { "type": "string", "description": "The JSON path of the request object to indicate the error location.", "example": "data.product.title" }, "info": { "type": "string", "description": "A human-readable description of the error.", "example": "Title is invalid" } } }, "Meta.v1": { "description": "The `Meta` model holds the metadata of the API response, including relevant error details for debugging purposes.\n\n
[url](../../docs/quickstart/request_errors.md)
", "type": "object", "x-examples": {}, "title": "Meta", "x-tags": [ "Envelope" ], "examples": [ { "code": 20000, "type": "OK", "message": "The request was successfully processed by AfterShip." } ], "additionalProperties": false, "required": [ "code", "type", "message" ], "properties": { "code": { "type": "number", "default": 20000, "example": 20000, "description": "Error code in integer format. For detailed information, please refer to the [Request Error](../../docs/quickstart/request_errors.md) introduction page." }, "type": { "type": "string", "minLength": 1, "example": "OK", "description": "Response type string for the reference. For detailed information, please refer to the [Request Error](../../docs/quickstart/request_errors.md) introduction page." }, "message": { "type": "string", "minLength": 1, "example": "The request was successfully processed by AfterShip.", "description": "Human-readable response message. For detailed information, please refer to the [Request Error](../../docs/quickstart/request_errors.md) introduction page." }, "errors": { "type": "array", "description": "Error detail object. Each error object contains a \"path\" key and an \"info\" key. The \"path\" is the JSON path of the request object to indicate the error location. The \"info\" is a human-readable description of the error.\n\n", "items": { "$ref": "#/components/schemas/Error.v1" } } } }, "Pagination.v2": { "title": "Pagination", "x-stoplight": { "id": "6twr4wc3wp9lu" }, "type": "object", "examples": [ { "page": 1, "limit": 10, "has_next_page": false } ], "description": "The `Pagination` holds the information for the pagination when the response contains multiple objects.", "x-tags": [ "Envelope" ], "properties": { "page": { "type": "integer", "x-stoplight": { "id": "5ld3b35057z8s" }, "description": "Page number." }, "limit": { "type": "integer", "x-stoplight": { "id": "qmvbmlfjchyh5" }, "description": "Maximum object count per page." }, "has_next_page": { "type": "boolean", "x-stoplight": { "id": "qtm2ifhlv0r4i" }, "description": "To indicate if next page is available." } } }, "Address.v1": { "description": "Billing address of the order.", "type": "object", "x-stoplight": { "id": "7cc87e0eb2a0d" }, "title": "Address", "examples": [ { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": null, "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+13525554500" } ], "x-tags": [ "Primitive" ], "additionalProperties": false, "required": [ "street_1", "state", "country_region" ], "properties": { "type": { "type": "string", "title": "The Type Schema", "description": "The type of address.", "enum": [ "business", "residential" ] }, "street_1": { "type": "string", "title": "The Street_1 Schema", "description": "First line of the street address.", "maxLength": 256 }, "street_2": { "type": [ "string", "null" ], "title": "The Street_2 Schema", "description": "Second line of the street address.", "maxLength": 256 }, "street_3": { "type": [ "string", "null" ], "title": "The Street_3 Schema", "description": "Third line of the street address.", "maxLength": 256 }, "city": { "type": "string", "title": "The City Schema", "description": "The location's city, town, or village.", "maxLength": 256 }, "state": { "type": "string", "title": "The State Schema", "description": "The state or region of the location, such as a province, state, or prefecture.", "maxLength": 256 }, "postal_code": { "type": "string", "title": "The Postal_code Schema", "description": "The postal code of the location (also known as zip code, postcode, Eircode, etc.).", "maxLength": 256 }, "country_region": { "type": "string", "title": "The Country Schema", "description": "The address country/region in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format. API will automatically convert input to uppercase.", "example": "USA", "pattern": "^[A-Z]{3}$" }, "company": { "type": "string", "title": "The Company Schema", "description": "The name of the company associated to the address.", "maxLength": 256 }, "first_name": { "type": "string", "title": "The First_name Schema", "description": "The first name of the person associated to the address.", "maxLength": 256 }, "last_name": { "type": "string", "title": "The Last_name Schema", "description": "The last name of the person associated to the address.", "maxLength": 256 }, "email": { "type": "string", "title": "The Email Schema", "description": "The email address of the person associated to the address.", "maxLength": 256 }, "phone": { "type": "string", "description": "The phone number of the person associated to the address.", "maxLength": 256 } } }, "Address_with_coordinate.v1": { "description": "The physical address and contact information of the location. For Location resources, `first_name` and `last_name` are joined into one contact name on write; on read, the full contact name is returned as `first_name` and `last_name` is empty. The `type` field is accepted by the schema but not used for Location resources — omit it on write; on read it is always empty.", "type": "object", "x-stoplight": { "id": "nu2sh0erm8041" }, "title": "AddressWithCoordinate", "examples": [ { "type": "business", "street_1": "1234 Elm Street", "street_2": "Apt 5", "street_3": null, "city": "New York", "state": "NY", "postal_code": "10001", "country_region": "USA", "company": "My Company", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+13525554500", "coordinate": { "latitude": 43, "longitude": -75 } } ], "x-tags": [ "Primitive" ], "additionalProperties": false, "required": [ "street_1", "state", "country_region" ], "properties": { "type": { "type": "string", "title": "The Type Schema", "description": "The type of address.", "enum": [ "business", "residential" ] }, "street_1": { "type": "string", "title": "The Street_1 Schema", "description": "First line of the street address.", "maxLength": 256 }, "street_2": { "type": [ "string", "null" ], "title": "The Street_2 Schema", "description": "Second line of the street address.", "maxLength": 256 }, "street_3": { "type": [ "string", "null" ], "title": "The Street_3 Schema", "description": "Third line of the street address.", "maxLength": 256 }, "city": { "type": "string", "title": "The City Schema", "description": "The location's city, town, or village.", "maxLength": 256 }, "state": { "type": "string", "title": "The State Schema", "description": "The state or region of the location, such as a province, state, or prefecture.", "maxLength": 256 }, "postal_code": { "type": "string", "title": "The Postal_code Schema", "description": "The postal code of the location (also known as zip code, postcode, Eircode, etc.).", "maxLength": 256 }, "country_region": { "type": "string", "title": "The Country Schema", "description": "The address country/region in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.", "example": "USA", "pattern": "^[A-Z]{3}$" }, "company": { "type": "string", "title": "The Company Schema", "description": "The name of the company associated to the address.", "maxLength": 256 }, "first_name": { "type": "string", "title": "The First_name Schema", "description": "The first name of the person associated to the address.", "maxLength": 256 }, "last_name": { "type": "string", "title": "The Last_name Schema", "description": "The last name of the person associated to the address.", "maxLength": 256 }, "email": { "type": "string", "title": "The Email Schema", "description": "The email address of the person associated to the address.", "maxLength": 256 }, "phone": { "type": "string", "description": "The phone number of the person associated to the address.", "maxLength": 256 }, "coordinate": { "type": "object", "description": "The coordinate of the address.", "properties": { "longitude": { "type": "number", "description": "The longitude of the address." }, "latitude": { "type": "number", "description": "The latitude of the address." } } } } }, "Customer.v1": { "description": "Customer information of the order.", "type": "object", "x-stoplight": { "id": "015a374050fbe" }, "title": "Customer", "examples": [ { "id": "5127837778090", "first_name": "John", "last_name": "Doe", "emails": [ "john.doe@example.com" ], "locale": "en-US", "phones": [ "+13525554500" ] } ], "x-tags": [ "Primitive" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "A unique identifier for the customer of your store platform. It could be the customer ID of your system, or a URL friendly name or slug which is unique in your system.", "maxLength": 32, "example": "5127837778090", "x-stoplight": { "id": "14lpgm5ogh4tc" } }, "first_name": { "type": "string", "description": "The customer's first name.", "maxLength": 256, "example": "John" }, "last_name": { "type": "string", "description": "The customer's last name.", "maxLength": 256, "example": "Doe" }, "emails": { "type": "array", "description": "The customer's email.", "maxItems": 100, "items": { "type": "string", "maxLength": 256 } }, "phones": { "type": "array", "description": "The customer's phone number.", "maxItems": 100, "items": { "type": "string" } }, "locale": { "type": "string", "description": "The language code of the customer, eg: en-US.", "maxLength": 128, "example": "en-US" } } }, "Money.v1": { "description": "The unit price of the item.", "title": "Money", "x-stoplight": { "id": "b2024e5c6f23f" }, "examples": [ { "currency": "USD", "amount": "10" } ], "type": "object", "x-tags": [ "Primitive" ], "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UYW", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWL" ], "description": "Currency code for the amount, adhering to the ISO 4217 standard.", "example": "USD" }, "amount": { "type": "string", "description": "The amount value in string format.", "example": "10" } } }, "Opening_hour_period.v1": { "title": "OpeningHourPeriod", "x-stoplight": { "id": "2g4w1syylsphw" }, "type": "object", "additionalProperties": false, "description": "The `OpeningHourPeriod` model provides detailed information about a location's operating hours for a specific day. It includes the start and end times, and indicates whether the location is open on that particular day.", "x-tags": [ "Primitive" ], "properties": { "open": { "type": "boolean", "default": false, "x-stoplight": { "id": "qbb3rmmdfdhxy" }, "description": "Indicate whether the store is open on this day. For locations that operate 24 hours, please set the value to `true`." }, "from": { "type": [ "string", "null" ], "x-stoplight": { "id": "fvyfkui68t3gt" }, "description": "The start time of the opening hour period in YY:MM format. For locations that operate 24 hours, please set the value to `null`.", "example": "10:30" }, "to": { "type": [ "string", "null" ], "x-stoplight": { "id": "sk5yjthy1achl" }, "description": "The end time of the opening hour period in YY:MM format. For locations that operate 24 hours, please set the value to `null`.", "example": "20:30" } }, "examples": [ { "open": true, "from": "10:30", "to": "20:30" } ] }, "Opening_hours.v1": { "description": "The regular opening hours of the location.", "title": "OpeningHours", "x-stoplight": { "id": "n7s4wz0dwk5ai" }, "type": "object", "properties": { "sunday": { "$ref": "#/components/schemas/Opening_hour_period.v1" }, "monday": { "$ref": "#/components/schemas/Opening_hour_period.v1" }, "tuesday": { "$ref": "#/components/schemas/Opening_hour_period.v1" }, "wednesday": { "$ref": "#/components/schemas/Opening_hour_period.v1" }, "thursday": { "$ref": "#/components/schemas/Opening_hour_period.v1" }, "friday": { "$ref": "#/components/schemas/Opening_hour_period.v1" }, "saturday": { "$ref": "#/components/schemas/Opening_hour_period.v1" } }, "x-tags": [ "Primitive" ] }, "Order_custom_fields.v1": { "x-stoplight": { "id": "ep64tykxqyu8q" }, "title": "OrderCustomFields", "type": "object", "additionalProperties": { "type": "string", "maxLength": 200, "x-stoplight": { "id": "1vm3fgpkplp4f" } }, "maxProperties": 10, "propertyNames": { "pattern": "^[a-z0-9-_]{1,20}$", "x-stoplight": { "id": "yjneg9em10bet" } }, "description": "Custom fields that accept an object with string field. In order to protect the privacy of your customers, do not include any personal data in custom fields.\n\nCustom fields for orders with the following constraints:\n- Maximum count for a key-value pair in a custom field object: 10\n- Maximum character limit for a key name: 20\n- Maximum value length: 200 characters\n- Supported value type: String only, no array, no (nested) object, no number, no null, no empty string\n- Allowed character set for key: `[a-z0-9-_]` only. A-Z is not allowed.\n- Allowed character set for value: No limit.\n\nNote: \n- When using the update order API, providing a new object will completely overwrite the existing one. Passing an empty object {} will overwrite it with an empty object.\n- The key-value pairs of this field will be copied to `fulfillment.trackings.*.custom_fields`" }, "Pickup.v1": { "x-stoplight": { "id": "xuy8sphna6ej7" }, "description": "To indicate the detailed pickup instruction of the order when the delivery method of the order is `pickup`.\n\nFor further details on pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../docs/common_scenarios/tracking/bopis.md).", "title": "Pickup", "type": "object", "x-tags": [ "Primitive" ], "properties": { "instructions": { "type": "string", "description": "Instructions for the pickup process.\n\nThe value specified in this field will take precedence if provided through the API. If not specified, it will default to the pickup location's instructions set in the AfterShip Admin Portal.", "example": "Shop open from Mon to Fri" }, "estimated_ready_for_pickup_at": { "type": "object", "description": "The expected date and time when the items in this fulfillment order will be ready for pickup.\n\nThis information will be displayed on the Brand Tracking Page and included in customer notifications.", "x-stoplight": { "id": "la1jawtei2np5" }, "properties": { "min": { "type": "string", "format": "date-time", "description": "The earliest anticipated date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2021-04-15T20:02:09Z" }, "max": { "type": "string", "format": "date-time", "description": "The latest anticipated date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2021-04-15T20:02:09Z" } } }, "pickup_deadline_at": { "type": "string", "x-stoplight": { "id": "lvr0jt3nk49b5" }, "format": "date-time", "description": "The latest time by which the pickup must be completed, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).\n\nThis information will be displayed on the Brand Tracking Page.\n\n", "example": "2021-04-15T20:02:09Z" } } }, "Pickup_location.v1": { "x-stoplight": { "id": "ou78lfdhqjx26" }, "description": "The location information where the fulfillment is designated to be pickup from. Mandatory when the delivery method of the fulfillment is `pickup`.", "title": "PickupLocation", "type": "object", "x-tags": [ "Primitive" ], "properties": { "location_id": { "type": "string", "x-stoplight": { "id": "o6v7ot5p5owq0" }, "description": "The unique identifier for the address. You can find or create the corresponding value [here](https://organization.automizely.com/warehouses).", "example": "e9ec84ff351e45e089a7b75ae497e1ae" }, "address": { "$ref": "#/components/schemas/Address_with_coordinate.v1", "x-stoplight": { "id": "xd0n6n4djzcml" }, "description": "Address of the pickup location." }, "opening_hours": { "$ref": "#/components/schemas/Opening_hours.v1", "x-stoplight": { "id": "xwxu19pd0nc0h" }, "description": "Opening hours information of the pickup location." } } }, "Status_timestamps.v1": { "x-stoplight": { "id": "8vvvtyweol0o1" }, "title": "StatusTimestamps", "type": "object", "description": "This object tracks the timestamps for each status change.\n\n- Explicit Input: If provides a timestamp, including null, it is stored as given.\n- Default Behavior: If no timestamp is specified and a status is set, the current time is automatically stored for that status. Example: If status is set to `open` and `opened_at` is not provided, `opened_at` will be assigned the current time.", "properties": { "opened_at": { "type": [ "string", "null" ], "x-stoplight": { "id": "fyfeos9fgfbuk" }, "format": "date-time", "description": "Datetime when the status was set to `open`." }, "canceled_at": { "type": [ "string", "null" ], "x-stoplight": { "id": "a5vzpw8hx3bah" }, "format": "date-time", "description": "Datetime when the status was set to `canceld`." }, "closed_at": { "type": [ "string", "null" ], "x-stoplight": { "id": "io9n4lfgu3kgv" }, "format": "date-time", "description": "Datetime when the status was set to `closed`." } } }, "Tracking.v1": { "title": "Tracking", "x-stoplight": { "id": "wugw7lvo5asco" }, "description": "Represents shipment tracking information. This object supports two mutually exclusive usage patterns:\n\nReference Mode: Pass the tracking ID which created via the Tracking API. This enables full tracking capabilities.\n\nInline Mode: Pass the tracking_number (and optional slug) directly. This is strictly for record-keeping purposes and does not create an active tracking task, and hence AfterShip system would not provide status updates to this tracking number.", "x-tags": [ "Primitive" ], "oneOf": [ { "title": "Reference Mode", "required": [ "id" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "x8fzwnwtejyio" }, "description": "The unique identifier of a tracking resource previously created via the Tracking API." } } }, { "title": "Inline Mode", "x-stoplight": { "id": "oqruujqsvdt22" }, "required": [ "tracking_number" ], "properties": { "tracking_number": { "type": "string", "x-stoplight": { "id": "a8z8ptxolucqz" } }, "slug": { "type": "string", "x-stoplight": { "id": "g2wj5ar3j83w6" }, "description": "Unique courier code. For a complete list of available courier codes, click here." } } } ], "type": "object" }, "Weight.v1": { "description": "The unit weight of the item.", "title": "Weight", "x-stoplight": { "id": "6ffc0efbd7bf5" }, "type": "object", "examples": [ { "unit": "kg", "value": 10 } ], "x-tags": [ "Primitive" ], "properties": { "unit": { "type": "string", "enum": [ "kg", "lb", "oz", "g" ], "description": "The weight unit eg: g or kg." }, "value": { "type": "number", "description": "The value of the weight.", "example": 10 } } }, "Fulfillment.v1": { "x-stoplight": { "id": "qnklgttqrn1fg" }, "title": "Fulfillment", "type": "object", "x-tags": [ "Resource" ], "description": "The `Fulfillment` model encapsulates the details of processing and delivering orders in an eCommerce context. It includes information such as fulfillment status, shipment tracking, the items to be fulfilled, and so on.\n\n
[url](../../docs/common_scenarios/tracking/bopis.md)
", "additionalProperties": false, "required": [ "id", "order_id", "delivery_method", "status", "line_items", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "3z259q39en5fr" }, "description": "The unique identifier of the fulfillment. If a custom ID was provided in the request, that value is used; otherwise, a system-generated UUID is assigned. You can use this ID to manage this resource in related API calls.", "example": "423562565" }, "order_id": { "type": "string", "x-stoplight": { "id": "9zw2pi119wjnl" }, "description": "It should be the same as the `order.id` of the `Order` resource.", "example": "5187092316403" }, "delivery_method": { "type": "string", "enum": [ "pickup", "shipping" ], "x-stoplight": { "id": "t9hsy1t30zkh8" }, "description": "Delivery method of the order. For BOPIS related feature, please specify `pickup`.\n\nFor more information about pickup order, please check the detailed [BOPIS introduction page](../../docs/common_scenarios/tracking/bopis.md).\n", "example": "shipping" }, "status": { "type": "string", "description": "The status of the fulfillment. Depending of on the `delivery_method`, the allowed values are different.\n\nAllowed values: \n\ndelivery_method is shipping:\n`pending`, `processing`, `shipped`, `canceled`, and the custom defined statuses.\n\ndelivery_method is pickup:\n`pending`, `processing`, `ready_for_pickup`, `picked_up`, `canceled`, and the custom defined statuses.", "example": "processing" }, "line_items": { "type": "array", "description": "The items which included in this fulifllment.", "items": { "type": "object", "required": [ "id", "product_id", "product_variant_id", "sku", "quantity" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "vh27skvspcy3e" }, "description": "A unique identifier for the line item in your system. The value should be exist in one of the items in the corresponding order.\n\nNote that it should be the same as the `order.items.*.id` of the `Order` resource.\n", "example": "13097711141107" }, "product_id": { "type": "string", "x-stoplight": { "id": "62p41vjigs5st" }, "description": "The ID of the product in your system.\n\nNote that it should be the same as the `product.id` of the `Product` resource.\n", "example": "8021450916083" }, "product_variant_id": { "type": "string", "description": "The ID of the product variant in source system.\n\nNote that it should be the same as the `product.variants.id` of the `Product` resource.", "example": "43768285298931" }, "product_title": { "type": "string", "description": "The title of the product.\n", "example": "Power Mobile Phone" }, "product_variant_title": { "type": "string", "description": "The title of the product variant.\n", "example": "Power Mobile Phone (While)" }, "sku": { "type": "string", "description": "The item's SKU (stock keeping unit).\n", "example": "SKU001" }, "quantity": { "type": "integer", "description": "The number of items in this fulfillment.", "example": 1 }, "unit_price": { "$ref": "#/components/schemas/Money.v1", "description": "The price of the item before discounts and taxes have been applied." }, "unit_weight": { "$ref": "#/components/schemas/Weight.v1", "description": "The item's weight." }, "image_urls": { "type": "array", "description": "Image urls of this product variant.", "items": { "type": "string", "example": "https://example.com/product/image.png" } } } } }, "source_created_at": { "type": "string", "format": "date-time", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the fulfillment was created in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "source_updated_at": { "type": "string", "format": "date-time", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the fulfillment was updated in your e-commerce system.", "example": "2021-04-16T20:02:09Z" }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time (ISO 8601 format) when the fulfillment was created in AfterShip.", "example": "2021-04-15T20:02:09Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time (ISO 8601 format) when the fulfillment was updated in AfterShip.", "example": "2021-04-16T20:02:09Z" }, "ship_from_location": { "type": "object", "description": "The location information where the fulfillment shipped from.", "additionalProperties": false, "properties": { "location_id": { "type": "string", "description": "The unique identifier for the location, as provided by AfterShip. You can manage and configure these locations [here](https://organization.automizely.com/warehouses).", "example": "489b4bdec18d45d387752d63fb51ee1d" }, "address": { "$ref": "#/components/schemas/Address.v1", "description": "The address object of this location." } } }, "pickup_location": { "$ref": "#/components/schemas/Pickup_location.v1", "description": "The location information where the fulfillment is designated to be pickup from." }, "trackings": { "type": "array", "description": "The shipment information of the fulfillment.", "items": { "$ref": "#/components/schemas/Tracking.v1" } }, "pickup_info": { "$ref": "#/components/schemas/Pickup.v1", "description": "The pickup information of the fulfillment.", "x-stoplight": { "id": "pl9ahbkgvzsfd" } } } }, "Location.v1": { "x-stoplight": { "id": "location-resource-v1" }, "type": "object", "x-tags": [ "Resource" ], "title": "Location", "description": "A `Location` represents a warehouse, store, or other physical place used for fulfillment, order processing, and pickup settings. Location resources are scoped to the organization and are not bound to a store.", "additionalProperties": false, "examples": [ { "id": "warehouse_1", "name": "SF Warehouse", "source": "manual", "address": { "company": "AfterShip", "first_name": "John Doe", "last_name": "", "phone": "+14155551234", "email": "john@example.com", "street_1": "123 Main St", "street_2": "Suite 100", "street_3": "", "city": "San Francisco", "state": "CA", "country_region": "USA", "postal_code": "94105", "coordinate": { "latitude": 37.7749, "longitude": -122.4194 } }, "timezone_identifier": "America/New_York", "opening_hours": { "sunday": { "open": false, "from": null, "to": null }, "monday": { "open": true, "from": "09:00", "to": "18:00" }, "tuesday": { "open": true, "from": "09:00", "to": "18:00" }, "wednesday": { "open": true, "from": "09:00", "to": "18:00" }, "thursday": { "open": true, "from": "09:00", "to": "18:00" }, "friday": { "open": true, "from": "09:00", "to": "18:00" }, "saturday": { "open": false, "from": null, "to": null } }, "order_processing": { "enabled": true, "order_cutoff_time": "14:00", "order_processing_duration_days": 0 }, "pickup_setting": { "enabled": true, "instructions": "Please pick up at the front desk.", "order_processing_duration_seconds_min": 3600, "order_processing_duration_seconds_max": 7200 }, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-04-24T00:00:00Z" } ], "required": [ "id", "name", "source", "address", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the location. For locations created through Commerce API, this is the custom ID supplied when creating the location, or a system-generated UUID if no custom ID was provided. For ecommerce platform-sourced locations, the ID is returned in the format `app---`.", "example": "warehouse_1", "readOnly": true }, "name": { "type": "string", "description": "The location name.", "maxLength": 256, "example": "SF Warehouse" }, "source": { "type": "string", "description": "The source of the location. `manual` means the location was created through Commerce API. `platform` means the location was imported from an ecommerce platform.", "enum": [ "manual", "platform" ], "readOnly": true, "example": "manual" }, "address": { "$ref": "#/components/schemas/Address_with_coordinate.v1", "description": "The physical address and contact information of the location. For Location resources, `first_name` and `last_name` are joined into one contact name on write; on read, the full contact name is returned as `first_name` and `last_name` is empty. The `type` field is accepted by the schema but not used for Location resources — omit it on write; on read it is always empty." }, "timezone_identifier": { "type": "string", "description": "The name of the timezone where the location is located, as defined by the [IANA timezone database standard](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "maxLength": 256, "example": "America/New_York" }, "opening_hours": { "$ref": "#/components/schemas/Opening_hours.v1", "description": "The regular opening hours of the location." }, "order_processing": { "type": "object", "additionalProperties": false, "description": "The order processing setting for this location.", "properties": { "enabled": { "type": "boolean", "description": "Whether order processing is enabled for this location.", "example": true }, "order_cutoff_time": { "type": "string", "description": "The daily cutoff time for processing orders in `HH:mm` format.", "example": "14:00" }, "order_processing_duration_days": { "type": "integer", "description": "The number of business days needed to process an order. Use `0` when fulfillment can be completed within 1 business day.", "minimum": 0, "example": 0 } } }, "pickup_setting": { "type": "object", "additionalProperties": false, "description": "The pickup setting for this location.", "properties": { "enabled": { "type": "boolean", "description": "Whether pickup is enabled for this location.", "example": true }, "instructions": { "type": "string", "description": "Pickup instructions shown to the customer.", "maxLength": 2048, "example": "Please pick up at the front desk." }, "order_processing_duration_seconds_min": { "type": "integer", "description": "The minimum number of seconds needed before the order is ready for pickup.", "minimum": 0, "example": 3600 }, "order_processing_duration_seconds_max": { "type": "integer", "description": "The maximum number of seconds needed before the order is ready for pickup.", "minimum": 0, "example": 7200 } } }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the location was created in AfterShip, formatted in ISO 8601.", "example": "2026-01-01T00:00:00Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the location was updated in AfterShip, formatted in ISO 8601.", "example": "2026-04-24T00:00:00Z", "readOnly": true } } }, "Order.v1": { "x-stoplight": { "id": "47628562601d9" }, "type": "object", "title": "Order", "x-tags": [ "Resource" ], "description": "The `Order` model represents a customer's order object of your store. It includes details such as the order ID of your store, customer information, products, quantities, pricing, order status, and so on. This model is essential for managing and tracking orders through the API.\n\n
[url](../../docs/common_scenarios/tracking/bopis.md)
", "additionalProperties": false, "required": [ "id", "number", "currency", "status", "order_total", "delivery_method" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the order. If a custom ID was provided in the request, that value is used; otherwise, a system-generated UUID is assigned. You can use this ID to manage this resource in related API calls.", "maxLength": 32, "example": "5187092316403", "x-stoplight": { "id": "8us4in94n6bjs" } }, "store": { "type": "object", "x-stoplight": { "id": "1m62f1y5411hp" }, "description": "Indicate which store the order belongs to.", "properties": { "id": { "type": "string", "x-stoplight": { "id": "nzslg67cs6zdb" }, "description": "The store ID by AfterShip. Please refer to the store resource for the details.", "example": "my-store-1", "readOnly": true } } }, "name": { "type": "string", "description": "The order name. Default is the same value as `number`.", "maxLength": 256, "example": "#1086" }, "number": { "type": "string", "description": "The order number.", "maxLength": 64, "example": "1086" }, "currency": { "type": "string", "description": "Specifies the currency for the order, adhering to the [ISO 4217 Currency Codes standard](https://en.wikipedia.org/wiki/ISO_4217).", "example": "HKD", "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": [ "open", "closed", "canceled" ], "description": "The status of the order.", "example": "open" }, "financial_status": { "type": [ "string", "null" ], "enum": [ "unpaid", "partially_paid", "paid", "partially_refunded", "refunded" ], "description": "The status of payments associated with the order." }, "fulfillment_status": { "type": "string", "enum": [ "unfulfilled", "partially_fulfilled", "fulfilled" ], "description": "The fulfillment status associated with the order. If not provided, this value is determined automatically. Since fulfillment has not been created at the time of order creation, it defaults to unfulfilled.\n\nIf you provide a value for this field when creating an order, you are responsible for updating the status manually from then onward. If you want AfterShip to manage the status automatically, do not provide this field when creating orders.", "example": "unfulfilled" }, "order_total": { "type": "string", "description": "The total price of the order.Final amount paid by the customer, including of charges.

\nFormula:
\n`order_total = subtotal + shipping_total + tax_total`", "maxLength": 100, "example": "97" }, "shipping_total": { "type": "string", "description": "The total shipping fee applied to the price of the order.", "maxLength": 100, "example": "5" }, "tax_total": { "type": "string", "description": "The sum of all the taxes applied to the order.", "maxLength": 100, "example": "10" }, "discount_total": { "type": "string", "description": "The total discounts applied to the order. The value should be equal to the sum of all item discounts.", "maxLength": 100, "example": "1" }, "subtotal": { "type": "string", "description": "Total after discounts, excluding taxes and shipping.
\n
\nFormula:
\n`subtotal = sum of all items' price`
\n
\n`1 item price = items.*.unit_price * items.*.quantity - items.*.discount`", "maxLength": 100, "example": "90" }, "items": { "type": "array", "description": "Purchased items of the order.", "maxItems": 100, "items": { "$ref": "#/components/schemas/Order_item.v1" } }, "note": { "type": "string", "description": "A note that the shop owner can optionally attach to the order.", "maxLength": 5000, "example": "Created by AfterShip" }, "source_created_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was created in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "source_updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was updated in your e-commerce system.", "example": "2021-04-16T20:02:09Z" }, "created_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was created in AfterShip system.", "example": "2021-04-15T20:02:09Z" }, "updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the order was created in AfterShip system.", "example": "2021-04-16T20:02:09Z" }, "customer": { "$ref": "#/components/schemas/Customer.v1", "description": "Customer information of the order." }, "shipping_address": { "$ref": "#/components/schemas/Address.v1", "description": "Shipping address of the order." }, "billing_address": { "$ref": "#/components/schemas/Address.v1", "description": "Billing address of the order." }, "tags": { "type": "array", "description": "Tags attached to the order.", "maxItems": 100, "items": { "type": "string", "example": "mobile-phone" } }, "shipping_method": { "type": "string", "description": "The name of the shipping method.", "maxLength": 256, "example": "standard shipping" }, "delivery_method": { "x-stoplight": { "id": "kg7aygp88v4vr" }, "enum": [ "shipping", "pickup" ], "type": "string", "description": "Delivery method of the order.\n\nFor orders requiring shipping to buyers, please specify `shipping`. For Buy Online, Pick Up In Store (BOPIS) orders, please specify `pickup`.\n\nFor further details on pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../../docs/common_scenarios/tracking/bopis.md).\n", "example": "shipping" }, "pickup_location": { "$ref": "#/components/schemas/Pickup_location.v1", "x-stoplight": { "id": "fgqz9c0104ma3" }, "description": "To indicate the pickup location of the order when the delivery method of the order is `pickup`.\n\nFor further details on pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../../docs/common_scenarios/tracking/bopis.md)." }, "pickup_info": { "$ref": "#/components/schemas/Pickup.v1", "x-stoplight": { "id": "j6bk78z88rumj" }, "description": "To indicate the detailed pickup instruction of the order when the delivery method of the order is `pickup`.\n\nFor further details on the pickup / BOPIS orders, refer to our comprehensive [BOPIS introduction page](../../docs/common_scenarios/tracking/bopis.md)." }, "status_timestamps": { "$ref": "#/components/schemas/Status_timestamps.v1", "x-stoplight": { "id": "1fkw5cyni92ii" } }, "custom_fields": { "$ref": "#/components/schemas/Order_custom_fields.v1", "x-stoplight": { "id": "g34whtdv9ibgv" } } } }, "Order_item.v1": { "title": "OrderItem", "x-stoplight": { "id": "82b3e826a399d" }, "type": "object", "description": "The `OrderItem` model represents an individual product within an order. It includes details such as the product ID, quantity, price and so on. This model ensures accurate item-level tracking for every order placed.\n\n", "x-tags": [ "Primitive" ], "examples": [ { "id": "13097711141107", "sku": "SKU001", "quantity": 1, "unit_weight": { "unit": "kg", "value": 10 }, "unit_price": { "currency": "USD", "amount": "10" }, "product_title": "Power Mobile Phone", "product_variant_title": "Power Mobile Phone Pro", "discount": "10", "tax": "10", "product_id": "8021450916083", "product_variant_id": "43768285298931", "hs_code": "554521", "origin_country_region": "USA", "image_urls": [ "https://www.example.com/product/phone/image.jpg" ], "product_tags": [ "mobile-phone" ], "product_categories": [ "mobile-phone" ], "returnable_quantity": 1 } ], "required": [ "id", "quantity", "product_title" ], "properties": { "id": { "type": "string", "description": "A unique identifier for the line item within the order. This should be provided when creating an order.\r\n\r\nPlease note:\r\n\r\n1. This is **NOT** the `product.id` of the `Product` resource.\r\n2. This ID should be the same as `fulfillment.*.line_items.id`.", "maxLength": 32, "example": "13097711141107", "x-stoplight": { "id": "idx4rym3su9ir" } }, "sku": { "type": "string", "description": "The item's SKU (stock keeping unit).", "maxLength": 256, "example": "SKU001", "x-stoplight": { "id": "47qw9lt2yocsm" } }, "quantity": { "type": "integer", "description": "The number of items that have been purchased.", "x-stoplight": { "id": "w4ek1dc410qax" }, "example": 1 }, "unit_weight": { "$ref": "#/components/schemas/Weight.v1", "description": "The item's weight.", "x-stoplight": { "id": "8htopnlftk8mn" } }, "unit_price": { "$ref": "#/components/schemas/Money.v1", "description": "The price of the item excluding discounts and taxes.\nPlease note that the item total price needs to meet the following formula: \n\n> item total price paid = unit_price*quantity - discount + tax", "x-stoplight": { "id": "ntn31dl89ci84" } }, "product_title": { "type": "string", "x-stoplight": { "id": "547mn5j3ip5gf" }, "description": "The title of the product.", "example": "Power Mobile Phone" }, "product_variant_title": { "type": "string", "description": "The title of the product variant.", "maxLength": 1024, "x-stoplight": { "id": "fvndkafxl3v9a" }, "example": "Power Mobile Phone Pro" }, "discount": { "type": "string", "description": "The total amount of the discount allocated to the line item. Including the discount applied only on this item and the allocated discount for the order level discount.", "maxLength": 100, "example": "10", "x-stoplight": { "id": "y4fsgrc3ubkr9" } }, "tax": { "type": "string", "description": "The total amount of the tax allocated to the line item.", "maxLength": 100, "example": "10", "x-stoplight": { "id": "3icpeo9spxeob" } }, "product_id": { "type": "string", "description": "The ID of the product in your system.\r\n\r\nNote that it should be the same as the `product.id` of the `Product` resource.", "maxLength": 128, "example": "8021450916083", "x-stoplight": { "id": "bqyjpv8jlmid3" } }, "product_variant_id": { "type": "string", "description": "The ID of the product variant in source system.\r\n\r\nNote that it should be the same as the `product.variants.id` of the `Product` resource.", "maxLength": 32, "example": "43768285298931", "x-stoplight": { "id": "ofcsdp3bto7aa" } }, "hs_code": { "type": "string", "description": "Harmonized System (HS) Codes.", "maxLength": 256, "example": "554521", "x-stoplight": { "id": "bvzc3g8rnn5v0" } }, "origin_country_region": { "type": "string", "description": "The origin country of this product. The field should in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.", "example": "USA", "pattern": "^[A-Z]{3}$", "x-stoplight": { "id": "9f4khsya41r8z" } }, "image_urls": { "type": "array", "description": "Image urls of this variant.", "maxItems": 100, "x-stoplight": { "id": "2n94mnl2jjrgq" }, "items": { "type": "string", "maxLength": 2048, "example": "https://www.example.com/product/phone/image.jpg", "x-stoplight": { "id": "82i1l3lhip5bp" } } }, "product_tags": { "type": "array", "description": "Product tags of this variant.", "x-stoplight": { "id": "o2lfm6bkgozxt" }, "items": { "type": "string", "maxLength": 256, "x-stoplight": { "id": "in8gcwxr3goqp" }, "example": "mobile-phone" } }, "product_categories": { "type": "array", "description": "Product categories of this variant.", "x-stoplight": { "id": "e52kc6v5tart0" }, "items": { "type": "string", "maxLength": 256, "example": "mobile-phone", "x-stoplight": { "id": "efyop56o4dltc" } } }, "returnable_quantity": { "type": "integer", "x-stoplight": { "id": "lgak2pxhsvtmx" }, "example": 1, "description": "This field allows you to set the maximum returnable quantity for an order item when importing the order. When a shopper requests a return, they will not be able to select a quantity exceeding this specified limit." } } }, "Product.v1": { "x-stoplight": { "id": "180c3db461386" }, "type": "object", "title": "Product", "x-tags": [ "Resource" ], "description": "The `Product` model represents an individual item of your store. It includes essential attributes such as product title, price, variants, SKU, and so on. This model is crucial for cataloging and managing the store's inventory effectively.", "additionalProperties": false, "examples": [ { "id": "546735673", "store": { "id": "my-store-1" }, "title": "Power Mobile Phone", "slug": "power-mobile-phone", "categories": [ "mobile-phone" ], "tags": [ "mobile-phone" ], "image_urls": [ "https://example.com/product/image.png" ], "url": "https://example.com/product/image.png", "published": true, "description": "string", "variants": [ { "id": "5634477687", "available_quantity": 1, "sku": "SKU001", "title": "Power Mobile Phone", "price": "10", "image_urls": [ "https://example.com/product/image.png" ], "compare_at_price": "string", "weight": { "unit": "kg", "value": 10 }, "allow_backorder": true, "options": [ { "name": "color", "value": "white" } ] } ], "source_created_at": "2021-04-15T20:02:09Z", "source_updated_at": "2021-04-15T20:02:09Z", "created_at": "2021-04-15T20:02:09Z", "updated_at": "2021-04-15T20:02:09Z" } ], "required": [ "id", "title", "image_urls", "variants" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the product. If a custom ID was provided in the request, that value is used; otherwise, a system-generated UUID is assigned. You can use this ID to manage this resource in related API calls.", "example": "fbc7245f23494576829c4b00609cf1ab", "readOnly": true }, "store": { "type": "object", "x-stoplight": { "id": "1m62f1y5411hp" }, "description": "Indicate which store the product belongs to.", "properties": { "id": { "type": "string", "x-stoplight": { "id": "nzslg67cs6zdb" }, "description": "The store ID by AfterShip. Please refer to the store resource for the details.", "example": "0ecb8ff7efa84d7d8f763ed7b21851d1", "readOnly": true } } }, "title": { "type": "string", "description": "The title of the product.", "example": "Power Mobile Phone" }, "slug": { "type": "string", "description": "URL friendly unique identifier for the product.", "example": "power-mobile-phone" }, "categories": { "type": "array", "description": "The categories associated with the product, used for filtering and search purposes.", "items": { "type": "string", "example": "mobile-phone" } }, "tags": { "type": "array", "description": "The tags associated with the product, used for filtering and search purposes.", "items": { "type": "string", "example": "mobile-phone" } }, "image_urls": { "type": "array", "description": "URLs of the product images.", "items": { "type": "string", "example": "https://example.com/product/image.png" } }, "url": { "type": "string", "description": "The URL of the product page in your online storefront.", "example": "https://example.com/product/image.png" }, "published": { "type": "boolean", "description": "To indicate whether the product has been published.", "default": true }, "description": { "type": "string", "description": "Description of the product." }, "variants": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "Product variant information.", "items": { "$ref": "#/components/schemas/Product_variant.v1" } }, "source_created_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was created in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "source_updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was updated in your e-commerce system.", "example": "2021-04-15T20:02:09Z" }, "created_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was created in AfterShip system.", "example": "2021-04-15T20:02:09Z" }, "updated_at": { "type": "string", "description": "The date and time, formatted in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), indicating when the product was updated in AfterShip system.", "example": "2021-04-15T20:02:09Z" } } }, "Product_variant.v1": { "title": "product_variant.v1", "x-stoplight": { "id": "9x15f6937soxi" }, "type": "object", "required": [ "id", "sku", "price" ], "properties": { "id": { "type": "string", "description": "A unique identifier for the product variant in your system.", "maxLength": 32, "example": "5634477687", "x-stoplight": { "id": "fv6ts8zm4xms8" } }, "sku": { "type": "string", "description": "The product SKU of the product variant.", "maxLength": 1024, "example": "SKU001" }, "price": { "type": "string", "description": "The price of the product variant.", "maxLength": 100, "example": "10" }, "available_quantity": { "type": "integer", "description": "Available quantity of the product variant.", "example": 1 }, "image_urls": { "type": "array", "maxItems": 100, "description": "The product image URL of the product variant.", "items": { "type": "string", "maxLength": 1024, "example": "https://example.com/product/image.png" } }, "title": { "type": "string", "description": "The title of the product variant.", "maxLength": 1024, "example": "Power Mobile Phone" }, "compare_at_price": { "type": "string", "description": "The original price of the item before an adjustment or a sale.", "maxLength": 100 }, "weight": { "$ref": "#/components/schemas/Weight.v1", "description": "The weight information of the product variant." }, "allow_backorder": { "type": "boolean", "description": "To specify whether customers are permitted to place an order for this out-of-stock product variant." }, "options": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "The custom product variant properties, such as size, color, and material.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The field name of the custom product property.", "maxLength": 256, "example": "color" }, "value": { "type": "string", "description": "The value of the custom product property.", "maxLength": 256, "example": "white" } } } } } }, "Store.v1": { "x-stoplight": { "id": "67b89e472d9db" }, "type": "object", "x-tags": [ "Resource" ], "title": "Store", "description": "A `Store` represents your actual retail outlet or an online store. All other resources within the API, including orders and products, are linked to a specific store.\n\nBefore you can utilize any features of the Commerce API, you must first create a store. After the store has been created, you will obtain a store ID. This ID is necessary for creating subsequent resources within the API.\n\n> **Activating the store**

Please contact the support team or your customer success manager together with your Storeto activate the connection between your store and AfterShip products.", "additionalProperties": false, "examples": [ { "id": "my-store-1", "created_at": "2024-05-06T12:32:00+01:00", "updated_at": "2024-05-06T12:32:00+01:00", "source_created_at": "2024-05-06T12:32:00+01:00", "source_updated_at": "2024-05-06T12:32:00+01:00", "platform": "aftership", "name": "My Store", "support_email": "support@example.com", "owner_email": "store_owner@example.com", "timezone_identifier": "America/New_York", "weight_unit": "lb", "currency": "USD", "phone": "+13525554500", "url": "https://www.example.com", "description": "My shop", "categories": [ "shoes" ], "address": { "street_1": "98 Circle", "street_2": null, "street_3": null, "city": "Daug City", "state": "New York", "postal_code": "10001", "country_region": "USA", "coordinate": { "latitude": 40, "longitude": 74 } } } ], "required": [ "name", "currency" ], "properties": { "id": { "type": "string", "description": "The id should be used as the `as-store-id` header value when calling other resource endpoints.\n\nThe unique identifier of the store. If a custom ID was provided in the request, that value is used; otherwise, a system-generated UUID is assigned. You can use this ID to manage this resource in related API calls.", "maxLength": 32, "example": "c10c3a0b90c24436bd158a0abbaf16d0", "readOnly": true }, "created_at": { "type": "string", "description": "The timestamp indicating when a store was created in AfterShip, formatted in ISO 8601 standard.", "example": "2024-05-06T12:32:00+01:00" }, "updated_at": { "type": "string", "description": "The timestamp indicating when a store was updated in AfterShip, formatted in ISO 8601 standard.", "example": "2024-05-06T12:32:00+01:00" }, "source_created_at": { "type": "string", "description": "Timestamp marking the creation of the store, formatted in [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2024-05-06T12:32:00+01:00" }, "source_updated_at": { "type": "string", "description": "The timestamp indicating the last update to the store, formatted in [ISO 8601 standard](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2024-05-06T12:32:00+01:00" }, "platform": { "description": "Identifies the platform associated with the store. For instance, a value of 'shopify' signifies that the store is based on Shopify, whereas a value of 'aftership' indicates the store originates from AfterShip.", "example": "aftership", "type": "string", "readOnly": true }, "name": { "type": "string", "description": "The shop's name.", "maxLength": 256, "example": "My Store" }, "support_email": { "type": "string", "description": "Support email address for your store.", "maxLength": 256, "example": "support@example.com" }, "owner_email": { "type": "string", "description": "The email address of the store owner.", "maxLength": 256, "example": "store_owner@example.com" }, "timezone_identifier": { "type": "string", "description": "The name of the timezone of your store located, as defined by the [IANA timezone database standard](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "maxLength": 256, "example": "America/New_York" }, "weight_unit": { "type": "string", "description": "Unit of measurement for weight used by the store, such as \"lb\" or \"kg\"", "maxLength": 64, "example": "lb" }, "currency": { "type": "string", "description": "Indicates the currency used by the store. The currency should be specified using the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) three-letter currency code (e.g., 'USD' for US Dollar, 'EUR' for Euro). ", "maxLength": 3, "example": "USD" }, "phone": { "type": "string", "description": "The store's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164).", "maxLength": 256, "example": "+13525554500" }, "url": { "type": "string", "description": "The URL of the store.", "maxLength": 2083, "example": "https://www.example.com" }, "description": { "type": "string", "description": "The text description of the store.", "maxLength": 10240, "example": "My shop" }, "categories": { "type": "array", "description": "The supported product category name of the store.", "maxItems": 100, "items": { "type": "string", "maxLength": 256, "example": "shoes" } }, "address": { "description": "The physical address of the store.", "type": "object", "additionalProperties": false, "properties": { "street_1": { "type": "string", "title": "The Street_1 Schema", "description": "First line of the store's street address.", "maxLength": 256, "example": "98 Circle" }, "street_2": { "type": [ "string", "null" ], "title": "The Street_2 Schema", "description": "Second line of the store's street address.", "maxLength": 256 }, "street_3": { "type": [ "string", "null" ], "title": "The Street_3 Schema", "description": "Third line of the store's street address.", "maxLength": 256 }, "city": { "type": "string", "title": "The City Schema", "description": "The city, town, or village where the store is located.", "maxLength": 256, "example": "Daug City" }, "state": { "type": "string", "title": "The State Schema", "description": "Indicates the state or region where the store is located, such as a province, state, or prefecture.", "maxLength": 256, "example": "New York" }, "postal_code": { "type": "string", "title": "The Postal_code Schema", "description": "The postal code of the store (also known as zip code, postcode, Eircode, etc.).", "maxLength": 256, "example": "10001" }, "country_region": { "type": "string", "title": "The Country Schema", "description": "The store's country/region in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.", "example": "USA", "pattern": "^[A-Z]{3}$" }, "coordinate": { "type": "object", "description": "Store address coordinate.", "additionalProperties": false, "properties": { "latitude": { "type": "number", "description": "The latitude of the store address.", "example": 40 }, "longitude": { "type": "number", "description": "The longitude of the store address.", "example": 74 } } } } } } } } }, "security": [ { "as-api-key": [] } ] }