asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
1e5a1398d8b5e92cea91d5338cc06ddcb6123ee1
medusa-store/docs/api/admin-spec3.yaml
Sebastian Rindom 1e5a1398d8 hotfix: docs build (#198) 
* fix: build

* fix: build

* fix: build

* fix: build
2021-03-10 16:15:06 +01:00

5932 lines
196 KiB
YAML
Raw Blame History

openapi: 3.0.0
info:
version: 1.0.0
title: Medusa Admin API
license:
name: MIT
tags:
- name: Auth
description: >-
Auth endpoints allows authorization of admin Users and manages their
sessions.
- name: Collection
x-resourceId: product_collection
- name: Customer
x-resourceId: customer
- name: Discount
x-resourceId: discount
- name: Gift Card
x-resourceId: gift_card
- name: Notification
x-resourceId: notification
- name: Order
x-resourceId: order
- name: Product
x-resourceId: product
- name: Region
x-resourceId: region
- name: Return
x-resourceId: return
- name: Shipping Option
x-resourceId: shipping_option
- name: Shipping Profile
x-resourceId: shipping_profile
- name: Swap
x-resourceId: swap
- name: Product Variant
x-resourceId: product_variant
servers:
- url: 'https://api.medusa-commerce.com/admin'
paths:
/auth:
post:
operationId: PostAuth
summary: Authenticate a User
description: Logs a User in and authorizes them to manage Store settings.
parameters: []
tags:
- Auth
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
customer:
$ref: '#/components/schemas/user'
requestBody:
content:
application/json:
schema:
type: object
required:
- email
- password
properties:
email:
type: string
description: The User's email.
password:
type: string
description: The User's password.
get:
operationId: GetAuth
summary: Get Session
description: Gets the currently logged in User.
tags:
- Auth
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
customer:
$ref: '#/components/schemas/user'
/collections:
post:
operationId: PostCollections
summary: Create a Product Collection
description: Creates a Product Collection.
requestBody:
content:
application/json:
schema:
required:
- title
properties:
title:
type: string
description: The title to identify the Collection by.
handle:
type: string
description: >-
An optional handle to be used in slugs, if none is provided
we will kebab-case the title.
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Collection
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
collection:
$ref: '#/components/schemas/product_collection'
get:
operationId: GetCollections
summary: List Product Collections
description: Retrieve a list of Product Collection.
tags:
- Collection
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
collection:
$ref: '#/components/schemas/product_collection'
'/collections/{id}':
delete:
operationId: DeleteCollectionsCollection
summary: Delete a Product Collection
description: Deletes a Product Collection.
parameters:
- in: path
name: id
required: true
description: The id of the Collection.
schema:
type: string
tags:
- Collection
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Collection
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetCollectionsCollection
summary: Retrieve a Product Collection
description: Retrieves a Product Collection.
parameters:
- in: path
name: id
required: true
description: The id of the Product Collection
schema:
type: string
tags:
- Collection
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
collection:
$ref: '#/components/schemas/product_collection'
post:
operationId: PostCollectionsCollection
summary: Update a Product Collection
description: Updates a Product Collection.
parameters:
- in: path
name: id
required: true
description: The id of the Collection.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
title:
type: string
description: The title to identify the Collection by.
handle:
type: string
description: >-
An optional handle to be used in slugs, if none is provided
we will kebab-case the title.
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Collection
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
collection:
$ref: '#/components/schemas/product_collection'
/customers:
post:
operationId: PostCustomers
summary: Create a Customer
description: Creates a Customer.
parameters: []
tags:
- Customer
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
customer:
$ref: '#/components/schemas/customer'
requestBody:
content:
application/json:
schema:
type: object
required:
- email
- first_name
- last_name
properties:
email:
type: string
description: The Customer's email address.
first_name:
type: string
description: The Customer's first name.
last_name:
type: string
description: The Customer's last name.
phone:
type: string
description: The Customer's phone number.
get:
operationId: GetCustomers
summary: List Customers
description: Retrieves a list of Customers.
tags:
- Customer
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
customer:
$ref: '#/components/schemas/customer'
'/customers/{id}':
get:
operationId: GetCustomersCustomer
summary: Retrieve a Customer
description: Retrieves a Customer.
parameters:
- in: path
name: id
required: true
description: The id of the Customer.
schema:
type: string
tags:
- Customer
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
customer:
$ref: '#/components/schemas/customer'
post:
operationId: PostCustomersCustomer
summary: Update a Customer
description: Updates a Customer.
parameters:
- in: path
name: id
required: true
description: The id of the Customer.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
first_name:
type: string
description: The Customer's first name.
last_name:
type: string
description: The Customer's last name.
phone:
description: The Customer's phone number.
type: object
tags:
- Customer
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
customer:
$ref: '#/components/schemas/customer'
'/discounts/{id}/regions/{region_id}':
post:
operationId: PostDiscountsDiscountRegionsRegion
summary: Adds Region availability
description: Adds a Region to the list of Regions that a Discount can be used in.
parameters:
- in: path
name: id
required: true
description: The id of the Discount.
schema:
type: string
- in: path
name: region_id
required: true
description: The id of the Region.
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
delete:
operationId: DeleteDiscountsDiscountRegionsRegion
summary: Remove Region availability
description: >-
Removes a Region from the list of Regions that a Discount can be used
in.
parameters:
- in: path
name: id
required: true
description: The id of the Discount.
schema:
type: string
- in: path
name: region_id
required: true
description: The id of the Region.
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
'/discounts/{id}/products/{product_id}':
post:
operationId: DeleteDiscountsDiscountProductsProduct
summary: Remove Product availability
description: >-
Removes a Product from the list of Products that a Discount can be used
for.
parameters:
- in: path
name: id
required: true
description: The id of the Discount.
schema:
type: string
- in: path
name: product_id
required: true
description: The id of the Product.
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
/discounts:
post:
operationId: PostDiscounts
summary: Creates a Discount
description: >-
Creates a Discount with a given set of rules that define how the
Discount behaves.
requestBody:
content:
application/json:
schema:
properties:
code:
type: string
description: A unique code that will be used to redeem the Discount
is_dynamic:
type: string
description: >-
Whether the Discount should have multiple instances of
itself, each with a different code. This can be useful for
automatically generated codes that all have to follow a
common set of rules.
rule:
description: The Discount Rule that defines how Discounts are calculated
oneOf:
- $ref: '#/components/schemas/discount_rule'
is_disabled:
type: boolean
description: >-
Whether the Discount code is disabled on creation. You will
have to enable it later to make it available to Customers.
starts_at:
type: string
format: date-time
description: The time at which the Discount should be available.
ends_at:
type: string
format: date-time
description: >-
The time at which the Discount should no longer be
available.
regions:
description: >-
A list of Region ids representing the Regions in which the
Discount can be used.
type: array
items:
type: string
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
get:
operationId: GetDiscounts
summary: List Discounts
description: Retrieves a list of Discounts
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
'/discounts/{id}/dynamic-codes':
post:
operationId: PostDiscountsDiscountDynamicCodes
summary: Create a dynamic Discount code
description: >-
Creates a unique code that can map to a parent Discount. This is useful
if you want to automatically generate codes with the same behaviour.
parameters:
- in: path
name: id
required: true
description: The id of the Discount to create the dynamic code from."
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
requestBody:
content:
application/json:
schema:
type: object
required:
- code
properties:
code:
type: string
description: The unique code that will be used to redeem the Discount.
metadata:
type: object
description: >-
An optional set of key-value paris to hold additional
information.
'/discounts/{id}':
delete:
operationId: DeleteDiscountsDiscount
summary: Delete a Discount
description: Deletes a Discount.
parameters:
- in: path
name: id
required: true
description: The id of the Discount
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Discount
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetDiscountsDiscount
summary: Retrieve a Discount
description: Retrieves a Discount
parameters:
- in: path
name: id
required: true
description: The id of the Discount
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
post:
operationId: PostDiscountsDiscount
summary: Update a Discount
description: >-
Updates a Discount with a given set of rules that define how the
Discount behaves.
parameters:
- in: path
name: id
required: true
description: The id of the Discount.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
code:
type: string
description: A unique code that will be used to redeem the Discount
is_dynamic:
type: string
description: >-
Whether the Discount should have multiple instances of
itself, each with a different code. This can be useful for
automatically generated codes that all have to follow a
common set of rules.
rule:
description: The Discount Rule that defines how Discounts are calculated
oneOf:
- $ref: '#/components/schemas/discount_rule'
is_disabled:
type: boolean
description: >-
Whether the Discount code is disabled on creation. You will
have to enable it later to make it available to Customers.
starts_at:
type: string
format: date-time
description: The time at which the Discount should be available.
ends_at:
type: string
format: date-time
description: >-
The time at which the Discount should no longer be
available.
regions:
description: >-
A list of Region ids representing the Regions in which the
Discount can be used.
type: array
items:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
'/discounts/{id}/dynamic-codes/{code}':
delete:
operationId: DeleteDiscountsDiscountDynamicCodesCode
summary: Delete a dynamic code
description: Deletes a dynamic code from a Discount.
parameters:
- in: path
name: id
required: true
description: The id of the Discount
schema:
type: string
- in: path
name: code
required: true
description: The id of the Discount
schema:
type: string
tags:
- Discount
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
discount:
$ref: '#/components/schemas/discount'
/gift-cards:
post:
operationId: PostGiftCards
summary: Create a Gift Card
description: >-
Creates a Gift Card that can redeemed by its unique code. The Gift Card
is only valid within 1 region.
requestBody:
content:
application/json:
schema:
properties:
value:
type: integer
description: >-
The value (excluding VAT) that the Gift Card should
represent.
is_disabled:
type: boolean
description: >-
Whether the Gift Card is disabled on creation. You will have
to enable it later to make it available to Customers.
ends_at:
type: string
format: date-time
description: >-
The time at which the Gift Card should no longer be
available.
region_id:
description: The id of the Region in which the Gift Card can be used.
type: array
items:
type: string
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Gift Card
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
gift_card:
$ref: '#/components/schemas/gift_card'
get:
operationId: GetGiftCards
summary: List Gift Cards
description: Retrieves a list of Gift Cards.
tags:
- Gift Card
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
gift_cards:
type: array
items:
$ref: '#/components/schemas/gift_card'
'/gift-cards/{id}':
delete:
operationId: DeleteGiftCardsGiftCard
summary: Delete a Gift Card
description: Deletes a Gift Card
parameters:
- in: path
name: id
required: true
description: The id of the Gift Card to delete.
schema:
type: string
tags:
- Gift Card
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Gift Card
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetGiftCardsGiftCard
summary: Retrieve a Gift Card
description: Retrieves a Gift Card.
parameters:
- in: path
name: id
required: true
description: The id of the Gift Card.
schema:
type: string
tags:
- Gift Card
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
gift_card:
$ref: '#/components/schemas/gift_card'
post:
operationId: PostGiftCardsGiftCard
summary: Create a Gift Card
description: >-
Creates a Gift Card that can redeemed by its unique code. The Gift Card
is only valid within 1 region.
parameters:
- in: path
name: id
required: true
description: The id of the Gift Card.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
balance:
type: integer
description: >-
The value (excluding VAT) that the Gift Card should
represent.
is_disabled:
type: boolean
description: >-
Whether the Gift Card is disabled on creation. You will have
to enable it later to make it available to Customers.
ends_at:
type: string
format: date-time
description: >-
The time at which the Gift Card should no longer be
available.
region_id:
description: The id of the Region in which the Gift Card can be used.
type: array
items:
type: string
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Gift Card
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
gift_card:
$ref: '#/components/schemas/gift_card'
/notifications:
get:
operationId: GetNotifications
summary: List Notifications
description: Retrieves a list of Notifications.
tags:
- Notification
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
notifications:
type: array
items:
$ref: '#/components/schemas/notification'
'/notifications/{id}/resend':
post:
operationId: PostNotificationsNotificationResend
summary: Resend Notification
description: >-
Resends a previously sent notifications, with the same data but
optionally to a different address
parameters:
- in: path
name: id
required: true
description: The id of the Notification
schema:
type: string
tags:
- Notification
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
notification:
$ref: '#/components/schemas/notification'
'/orders/{id}/shipping-methods':
post:
operationId: PostOrdersOrderShippingMethods
summary: Add a Shipping Method
description: >-
Adds a Shipping Method to an Order. If another Shipping Method exists
with the same Shipping Profile, the previous Shipping Method will be
replaced.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
requestBody:
content:
application/json:
schema:
type: object
required:
- price
- option_id
- data
properties:
price:
type: integer
description: >-
The price (excluding VAT) that should be charged for the
Shipping Method
option_id:
type: string
description: >-
The id of the Shipping Option to create the Shipping Method
from.
data:
type: object
description: >-
The data required for the Shipping Option to create a
Shipping Method. This will depend on the Fulfillment
Provider.
'/orders/{id}/cancel':
post:
operationId: PostOrdersOrderCancel
summary: Cancel an Order
description: >-
Registers an Order as canceled. This triggers a flow that will cancel
any created Fulfillments and Payments, may fail if the Payment or
Fulfillment Provider is unable to cancel the Payment/Fulfillment.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/capture':
post:
operationId: PostOrdersOrderCapture
summary: Capture an Order
description: Captures all the Payments associated with an Order.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/claims/{claim_id}/shipments':
post:
operationId: PostOrdersOrderClaimsClaimShipments
summary: Create Claim Shipment
description: Registers a Claim Fulfillment as shipped.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: claim_id
required: true
description: The id of the Claim.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
fulfillment_id:
description: The id of the Fulfillment.
type: string
tracking_numbers:
description: The tracking numbers for the shipment.
type: array
items:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/order/{id}/claims':
post:
operationId: PostOrdersOrderClaims
summary: Create a Claim
description: Creates a Claim.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
type:
description: >-
The type of the Claim. This will determine how the Claim is
treated: `replace` Claims will result in a Fulfillment with
new items being created, while a `refund` Claim will refund
the amount paid for the claimed items.
type: string
enum:
- replace
- refund
claim_items:
description: The Claim Items that the Claim will consist of.
type: array
items:
properties:
item_id:
description: The id of the Line Item that will be claimed.
type: string
quantity:
description: The number of items that will be returned
type: integer
note:
description: >-
Short text describing the Claim Item in further
detail.
type: string
reason:
description: The reason for the Claim
type: string
enum:
- missing_item
- wrong_item
- production_failure
- other
tags:
description: A list o tags to add to the Claim Item
type: array
items:
type: string
images:
description: >-
A list of image URL's that will be associated with the
Claim
items:
type: string
return_shipping:
description: >-
Optional details for the Return Shipping Method, if the
items are to be sent back.
type: object
properties:
option_id:
type: string
description: >-
The id of the Shipping Option to create the Shipping
Method from.
price:
type: integer
description: The price to charge for the Shipping Method.
additional_items:
description: >-
The new items to send to the Customer when the Claim type is
Replace.
type: array
items:
properties:
variant_id:
description: The id of the Product Variant to ship.
type: string
quantity:
description: The quantity of the Product Variant to ship.
type: integer
shipping_methods:
description: The Shipping Methods to send the additional Line Items with.
type: array
items:
properties:
id:
description: The id of an existing Shipping Method
type: string
option_id:
description: >-
The id of the Shipping Option to create a Shipping
Method from
type: string
price:
description: The price to charge for the Shipping Method
type: integer
refund_amount:
description: >-
The amount to refund the Customer when the Claim type is
`refund`.
type: integer
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/fulfillments':
post:
operationId: PostOrdersOrderFulfillments
summary: Create a Fulfillment
description: >-
Creates a Fulfillment of an Order - will notify Fulfillment Providers to
prepare a shipment.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
items:
description: The Line Items to include in the Fulfillment.
type: array
items:
properties:
item_id:
description: The id of Line Item to fulfill.
type: string
quantity:
description: The quantity of the Line Item to fulfill.
type: integer
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/shipment':
post:
operationId: PostOrdersOrderShipment
summary: Create a Shipment
description: Registers a Fulfillment as shipped.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
fulfillment_id:
description: The id of the Fulfillment.
type: string
tracking_numbers:
description: The tracking numbers for the shipment.
type: array
items:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/swaps/{swap_id}/shipments':
post:
operationId: PostOrdersOrderSwapsSwapShipments
summary: Create Swap Shipment
description: Registers a Swap Fulfillment as shipped.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: swap_id
required: true
description: The id of the Swap.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
fulfillment_id:
description: The id of the Fulfillment.
type: string
tracking_numbers:
description: The tracking numbers for the shipment.
type: array
items:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/order/{id}/swaps':
post:
operationId: PostOrdersOrderSwaps
summary: Create a Swap
description: >-
Creates a Swap. Swaps are used to handle Return of previously purchased
goods and Fulfillment of replacements simultaneously.
parameters:
- in: path
name: id
required: true
description: The id of the Swap.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
return_items:
description: The Line Items to return as part of the Swap.
type: array
items:
properties:
item_id:
description: The id of the Line Item that will be claimed.
type: string
quantity:
description: The number of items that will be returned
type: integer
return_shipping:
description: How the Swap will be returned.
type: object
properties:
option_id:
type: string
description: >-
The id of the Shipping Option to create the Shipping
Method from.
price:
type: integer
description: The price to charge for the Shipping Method.
additional_items:
description: The new items to send to the Customer.
type: array
items:
properties:
variant_id:
description: The id of the Product Variant to ship.
type: string
quantity:
description: The quantity of the Product Variant to ship.
type: integer
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/order/{id}/metadata/{key}':
delete:
operationId: DeleteOrdersOrderMetadataKey
summary: Delete Metadata
description: Deletes a metadata key.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: key
required: true
description: The metadata key.
schema:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/claims/{claim_id}/fulfillments':
post:
operationId: PostOrdersOrderClaimsClaimFulfillments
summary: Create a Claim Fulfillment
description: Creates a Fulfillment for a Claim.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: claim_id
required: true
description: The id of the Claim.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/swaps/{swap_id}/fulfillments':
post:
operationId: PostOrdersOrderSwapsSwapFulfillments
summary: Create a Swap Fulfillment
description: Creates a Fulfillment for a Swap.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: swap_id
required: true
description: The id of the Swap.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}':
get:
operationId: GetOrdersOrder
summary: Retrieve an Order
description: Retrieves an Order
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
/orders:
get:
operationId: GetOrders
summary: List Orders
description: Retrieves an list of Orders
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/swaps/{swap_id}/process-payment':
post:
operationId: PostOrdersOrderSwapsSwapProcessPayment
summary: Process a Swap difference
description: >-
When there are differences between the returned and shipped Products in
a Swap, the difference must be processed. Either a Refund will be issued
or a Payment will be captured.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: swap_id
required: true
description: The id of the Swap.
schema:
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/returns/{return_id}/receive':
post:
operationId: PostOrdersOrderReturnsReturnReceive
summary: Receive a Return
description: Registers a Return as received.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: return_id
required: true
description: The id of the Return.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
items:
description: The Line Items that have been received.
type: array
items:
properties:
item_id:
description: The id of the Line Item.
type: string
quantity:
description: The quantity of the Line Item.
type: integer
refund:
description: The amount to refund.
type: integer
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/swaps/{swap_id}/receive':
post:
operationId: PostOrdersOrderSwapsSwapReceive
summary: Receive a Swap
description: Registers a Swap as received.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: swap_id
required: true
description: The id of the Swap.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
items:
description: The Line Items that have been received.
type: array
items:
properties:
item_id:
description: The id of the Line Item.
type: string
quantity:
description: The quantity of the Line Item.
type: integer
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/refunds':
post:
operationId: PostOrdersOrderRefunds
summary: Create a Refund
description: Issues a Refund.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
required:
- amount
- reason
properties:
amount:
description: The amount to refund.
type: integer
reason:
description: The reason for the Refund.
type: string
note:
description: A not with additional details about the Refund.
type: string
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/orders/{id}/returns':
post:
operationId: PostOrdersOrderReturns
summary: Request a Return
description: >-
Requests a Return. If applicable a return label will be created and
other plugins notified.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
items:
description: The Line Items that will be returned.
type: array
items:
properties:
item_id:
description: The id of the Line Item.
type: string
quantity:
description: The quantity of the Line Item.
type: integer
return_shipping:
description: >-
The Shipping Method to be used to handle the return
shipment.
type: object
properties:
option_id:
type: string
description: >-
The id of the Shipping Option to create the Shipping
Method from.
price:
type: integer
description: The price to charge for the Shipping Method.
receive_now:
description: >-
A flag to indicate if the Return should be registerd as
received immediately.
type: boolean
refund:
description: The amount to refund.
type: integer
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/order/{id}/claims/{claim_id}':
post:
operationId: PostOrdersOrderClaimsClaim
summary: Update a Claim
description: Updates a Claim.
parameters:
- in: path
name: id
required: true
description: The id of the Order.
schema:
type: string
- in: path
name: claim_id
required: true
description: The id of the Claim.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
claim_items:
description: The Claim Items that the Claim will consist of.
type: array
items:
properties:
id:
description: The id of the Claim Item.
type: string
item_id:
description: The id of the Line Item that will be claimed.
type: string
quantity:
description: The number of items that will be returned
type: integer
note:
description: >-
Short text describing the Claim Item in further
detail.
type: string
reason:
description: The reason for the Claim
type: string
enum:
- missing_item
- wrong_item
- production_failure
- other
tags:
description: A list o tags to add to the Claim Item
type: array
items:
type: string
images:
description: >-
A list of image URL's that will be associated with the
Claim
items:
type: string
shipping_methods:
description: The Shipping Methods to send the additional Line Items with.
type: array
items:
properties:
id:
description: The id of an existing Shipping Method
type: string
option_id:
description: >-
The id of the Shipping Option to create a Shipping
Method from
type: string
price:
description: The price to charge for the Shipping Method
type: integer
metadata:
description: >-
An optional set of key-value pairs to hold additional
information.
type: object
tags:
- Order
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
order:
$ref: '#/components/schemas/order'
'/products/{id}/options':
post:
operationId: PostProductsProductOptions
summary: Add an Option
description: Adds a Product Option to a Product
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
title:
description: >-
The title the Product Option will be identified by i.e.
"Size"
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
/products:
post:
operationId: PostProducts
summary: Create a Product
description: Creates a Product
requestBody:
content:
application/json:
schema:
properties:
title:
description: The title of the Product
type: string
subtitle:
description: The subtitle of the Product
type: string
description:
description: A description of the Product.
type: string
is_giftcard:
description: >-
A flag to indicate if the Product represents a Gift Card.
Purchasing Products with this flag set to `true` will result
in a Gift Card being created.
type: boolean
images:
description: Images of the Product.
type: array
items:
type: string
thumbnail:
description: The thumbnail to use for the Product.
type: string
handle:
description: A unique handle to identify the Product by.
type: string
type:
description: The Product Type to associate the Product with.
type: object
properties:
value:
description: The value of the Product Type.
type: string
collection_id:
description: The id of the Collection the Product should belong to.
type: string
tags:
description: Tags to associate the Product with.
type: array
items:
properties:
id:
description: The id of an existing Tag.
type: string
value:
description: 'The value of the Tag, these will be upserted.'
type: string
options:
description: >-
The Options that the Product should have. These define on
which properties the Product's Product Variants will differ.
type: array
items:
properties:
title:
description: The title to identify the Product Option by.
type: string
variants:
description: A list of Product Variants to create with the Product.
type: array
items:
properties:
title:
description: The title to identify the Product Variant by.
type: string
sku:
description: The unique SKU for the Product Variant.
type: string
ean:
description: The EAN number of the item.
type: string
upc:
description: The UPC number of the item.
type: string
barcode:
description: A generic GTIN field for the Product Variant.
type: string
hs_code:
description: The Harmonized System code for the Product Variant.
type: string
inventory_quantity:
description: The amount of stock kept for the Product Variant.
type: integer
allow_backorder:
description: >-
Whether the Product Variant can be purchased when out
of stock.
type: boolean
manage_inventory:
description: >-
Whether Medusa should keep track of the inventory for
this Product Variant.
type: boolean
weight:
description: The wieght of the Product Variant.
type: string
length:
description: The length of the Product Variant.
type: string
height:
description: The height of the Product Variant.
type: string
width:
description: The width of the Product Variant.
type: string
origin_country:
description: The country of origin of the Product Variant.
type: string
mid_code:
description: >-
The Manufacturer Identification code for the Product
Variant.
type: string
material:
description: The material composition of the Product Variant.
type: string
metadata:
description: >-
An optional set of key-value pairs with additional
information.
type: object
prices:
type: array
items:
properties:
region_id:
description: >-
The id of the Region for which the price is
used.
type: string
currency_code:
description: >-
The 3 character ISO currency code for which the
price will be used.
type: string
amount:
description: The amount to charge for the Product Variant.
type: integer
sale_amount:
description: >-
The sale amount to charge for the Product
Variant.
type: integer
options:
type: array
items:
properties:
value:
description: >-
The value to give for the Product Option at the
same index in the Product's `options` field.
type: string
weight:
description: The wieght of the Product.
type: string
length:
description: The length of the Product.
type: string
height:
description: The height of the Product.
type: string
width:
description: The width of the Product.
type: string
origin_country:
description: The country of origin of the Product.
type: string
mid_code:
description: The Manufacturer Identification code for the Product.
type: string
material:
description: The material composition of the Product.
type: string
metadata:
description: >-
An optional set of key-value pairs with additional
information.
type: object
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
get:
operationId: GetProducts
summary: List Product
description: Retrieves a list of Product
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
count:
description: The number of Products.
type: integer
offset:
description: The offset of the Product query.
type: integer
limit:
description: The limit of the Product query.
type: integer
products:
type: array
items:
$ref: '#/components/schemas/product'
'/products/{id}/variants':
post:
operationId: PostProductsProductVariants
summary: Create a Product Variant
description: >-
Creates a Product Variant. Each Product Variant must have a unique
combination of Product Option Values.
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
title:
description: The title to identify the Product Variant by.
type: string
sku:
description: The unique SKU for the Product Variant.
type: string
ean:
description: The EAN number of the item.
type: string
upc:
description: The UPC number of the item.
type: string
barcode:
description: A generic GTIN field for the Product Variant.
type: string
hs_code:
description: The Harmonized System code for the Product Variant.
type: string
inventory_quantity:
description: The amount of stock kept for the Product Variant.
type: integer
allow_backorder:
description: >-
Whether the Product Variant can be purchased when out of
stock.
type: boolean
manage_inventory:
description: >-
Whether Medusa should keep track of the inventory for this
Product Variant.
type: boolean
weight:
description: The wieght of the Product Variant.
type: string
length:
description: The length of the Product Variant.
type: string
height:
description: The height of the Product Variant.
type: string
width:
description: The width of the Product Variant.
type: string
origin_country:
description: The country of origin of the Product Variant.
type: string
mid_code:
description: >-
The Manufacturer Identification code for the Product
Variant.
type: string
material:
description: The material composition of the Product Variant.
type: string
metadata:
description: >-
An optional set of key-value pairs with additional
information.
type: object
prices:
type: array
items:
properties:
region_id:
description: The id of the Region for which the price is used.
type: string
currency_code:
description: >-
The 3 character ISO currency code for which the price
will be used.
type: string
amount:
description: The amount to charge for the Product Variant.
type: integer
sale_amount:
description: The sale amount to charge for the Product Variant.
type: integer
options:
type: array
items:
properties:
option_id:
description: The id of the Product Option to set the value for.
type: string
value:
description: The value to give for the Product Option.
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
get:
operationId: GetProductsProductVariants
summary: List a Product's Product Variants
description: Retrieves a list of the Product Variants associated with a Product.
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
variants:
type: array
items:
$ref: '#/components/schemas/product_variant'
'/products/{id}/options/{option_id}':
delete:
operationId: DeleteProductsProductOptionsOption
summary: Delete a Product Option
description: >-
Deletes a Product Option. Before a Product Option can be deleted all
Option Values for the Product Option must be the same. You may, for
example, have to delete some of your variants prior to deleting the
Product Option
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
- in: path
name: option_id
required: true
description: The id of the Product Option.
schema:
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Product Option
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
product:
$ref: '#/components/schemas/product'
post:
operationId: PostProductsProductOptionsOption
summary: Update a Product Option.
description: Updates a Product Option
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
- in: path
name: option_id
required: true
description: The id of the Product Option.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
title:
description: The title of the Product Option
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
'/products/{id}':
delete:
operationId: DeleteProductsProduct
summary: Delete a Product
description: Deletes a Product and it's associated Product Variants.
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Product.
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetProductsProduct
summary: Retrieve a Product
description: Retrieves a Product.
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
post:
operationId: PostProductsProduct
summary: Update a Product
description: Updates a Product
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
title:
description: The title of the Product
type: string
subtitle:
description: The subtitle of the Product
type: string
description:
description: A description of the Product.
type: string
is_giftcard:
description: >-
A flag to indicate if the Product represents a Gift Card.
Purchasing Products with this flag set to `true` will result
in a Gift Card being created.
type: boolean
images:
description: Images of the Product.
type: array
items:
type: string
thumbnail:
description: The thumbnail to use for the Product.
type: string
handle:
description: A unique handle to identify the Product by.
type: string
type:
description: The Product Type to associate the Product with.
type: object
properties:
value:
description: The value of the Product Type.
type: string
collection_id:
description: The id of the Collection the Product should belong to.
type: string
tags:
description: Tags to associate the Product with.
type: array
items:
properties:
id:
description: The id of an existing Tag.
type: string
value:
description: 'The value of the Tag, these will be upserted.'
type: string
options:
description: >-
The Options that the Product should have. These define on
which properties the Product's Product Variants will differ.
type: array
items:
properties:
title:
description: The title to identify the Product Option by.
type: string
variants:
description: A list of Product Variants to create with the Product.
type: array
items:
properties:
title:
description: The title to identify the Product Variant by.
type: string
sku:
description: The unique SKU for the Product Variant.
type: string
ean:
description: The EAN number of the item.
type: string
upc:
description: The UPC number of the item.
type: string
barcode:
description: A generic GTIN field for the Product Variant.
type: string
hs_code:
description: The Harmonized System code for the Product Variant.
type: string
inventory_quantity:
description: The amount of stock kept for the Product Variant.
type: integer
allow_backorder:
description: >-
Whether the Product Variant can be purchased when out
of stock.
type: boolean
manage_inventory:
description: >-
Whether Medusa should keep track of the inventory for
this Product Variant.
type: boolean
weight:
description: The wieght of the Product Variant.
type: string
length:
description: The length of the Product Variant.
type: string
height:
description: The height of the Product Variant.
type: string
width:
description: The width of the Product Variant.
type: string
origin_country:
description: The country of origin of the Product Variant.
type: string
mid_code:
description: >-
The Manufacturer Identification code for the Product
Variant.
type: string
material:
description: The material composition of the Product Variant.
type: string
metadata:
description: >-
An optional set of key-value pairs with additional
information.
type: object
prices:
type: array
items:
properties:
region_id:
description: >-
The id of the Region for which the price is
used.
type: string
currency_code:
description: >-
The 3 character ISO currency code for which the
price will be used.
type: string
amount:
description: The amount to charge for the Product Variant.
type: integer
sale_amount:
description: >-
The sale amount to charge for the Product
Variant.
type: integer
options:
type: array
items:
properties:
value:
description: >-
The value to give for the Product Option at the
same index in the Product's `options` field.
type: string
weight:
description: The wieght of the Product.
type: string
length:
description: The length of the Product.
type: string
height:
description: The height of the Product.
type: string
width:
description: The width of the Product.
type: string
origin_country:
description: The country of origin of the Product.
type: string
mid_code:
description: The Manufacturer Identification code for the Product.
type: string
material:
description: The material composition of the Product.
type: string
metadata:
description: >-
An optional set of key-value pairs with additional
information.
type: object
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
'/products/{id}/variants/{variant_id}':
delete:
operationId: DeleteProductsProductVariantsVariant
summary: Delete a Product Variant
description: Deletes a Product Variant.
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
- in: path
name: variant_id
required: true
description: The id of the Product Variant.
schema:
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Product Variant.
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
post:
operationId: PostProductsProductVariantsVariant
summary: Update a Product Variant
description: Update a Product Variant.
parameters:
- in: path
name: id
required: true
description: The id of the Product.
schema:
type: string
- in: path
name: variant_id
required: true
description: The id of the Product Variant.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
title:
description: The title to identify the Product Variant by.
type: string
sku:
description: The unique SKU for the Product Variant.
type: string
ean:
description: The EAN number of the item.
type: string
upc:
description: The UPC number of the item.
type: string
barcode:
description: A generic GTIN field for the Product Variant.
type: string
hs_code:
description: The Harmonized System code for the Product Variant.
type: string
inventory_quantity:
description: The amount of stock kept for the Product Variant.
type: integer
allow_backorder:
description: >-
Whether the Product Variant can be purchased when out of
stock.
type: boolean
manage_inventory:
description: >-
Whether Medusa should keep track of the inventory for this
Product Variant.
type: boolean
weight:
description: The wieght of the Product Variant.
type: string
length:
description: The length of the Product Variant.
type: string
height:
description: The height of the Product Variant.
type: string
width:
description: The width of the Product Variant.
type: string
origin_country:
description: The country of origin of the Product Variant.
type: string
mid_code:
description: >-
The Manufacturer Identification code for the Product
Variant.
type: string
material:
description: The material composition of the Product Variant.
type: string
metadata:
description: >-
An optional set of key-value pairs with additional
information.
type: object
prices:
type: array
items:
properties:
region_id:
description: The id of the Region for which the price is used.
type: string
currency_code:
description: >-
The 3 character ISO currency code for which the price
will be used.
type: string
amount:
description: The amount to charge for the Product Variant.
type: integer
sale_amount:
description: The sale amount to charge for the Product Variant.
type: integer
options:
type: array
items:
properties:
option_id:
description: The id of the Product Option to set the value for.
type: string
value:
description: The value to give for the Product Option.
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
product:
$ref: '#/components/schemas/product'
/products/types:
get:
operationId: GetProductsTypes
summary: List Product Types
description: Retrieves a list of Product Types.
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
types:
type: array
items:
$ref: '#/components/schemas/product_type'
'/regions/{id}/countries':
post:
operationId: PostRegionsRegionCountries
summary: Add Country
description: Adds a Country to the list of Countries in a Region
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
country_code:
description: The 2 character ISO code for the Country.
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
'/regions/{id}/fulfillment-providers':
post:
operationId: PostRegionsRegionFulfillmentProviders
summary: Add Fulfillment Provider
description: Adds a Fulfillment Provider to a Region
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
provider_id:
description: The id of the Fulfillment Provider to add.
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
'/regions/{id}/payment-providers':
post:
operationId: PostRegionsRegionPaymentProviders
summary: Add Payment Provider
description: Adds a Payment Provider to a Region
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
provider_id:
description: The id of the Payment Provider to add.
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
/regions:
post:
operationId: PostRegions
summary: Create a Region
description: Creates a Region
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Region
type: string
currency_code:
description: The 3 character ISO currency code to use for the Region.
type: string
tax_code:
description: An optional tax code the Region.
type: string
tax_rate:
description: The tax rate to use on Orders in the Region.
type: number
payment_providers:
description: >-
A list of Payment Providers that should be enabled for the
Region
type: array
items:
type: string
fulfillment_providers:
description: >-
A list of Fulfillment Providers that should be enabled for
the Region
type: array
items:
type: string
countries:
description: A list of countries that should be included in the Region.
type: array
items:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
get:
operationId: GetRegions
summary: List Regions
description: Retrieves a list of Regions.
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
regions:
type: array
items:
$ref: '#/components/schemas/region'
'/regions/{id}/metadata/{key}':
delete:
operationId: DeleteRegionsRegionMetadataKey
summary: Delete Metadata
description: Deletes a metadata key.
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
- in: path
name: key
required: true
description: The metadata key.
schema:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
'/regions/{id}':
delete:
operationId: DeleteRegionsRegion
summary: Delete a Region
description: Deletes a Region.
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Region.
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetRegionsRegion
summary: Retrieve a Region
description: Retrieves a Region.
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
post:
operationId: PostRegionsRegion
summary: Update a Region
description: Updates a Region
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Region
type: string
currency_code:
description: The 3 character ISO currency code to use for the Region.
type: string
tax_code:
description: An optional tax code the Region.
type: string
tax_rate:
description: The tax rate to use on Orders in the Region.
type: number
payment_providers:
description: >-
A list of Payment Providers that should be enabled for the
Region
type: array
items:
type: string
fulfillment_providers:
description: >-
A list of Fulfillment Providers that should be enabled for
the Region
type: array
items:
type: string
countries:
description: A list of countries that should be included in the Region.
type: array
items:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
'/regions/{id}/fulfillment-options':
get:
operationId: GetRegionsRegionFulfillmentOptions
summary: List Fulfillment Options available in the Region
description: Gathers all the fulfillment options available to in the Region.
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
tags:
- Product
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
fulfillment_options:
type: array
items:
type: object
'/regions/{id}/countries/{country_code}':
delete:
operationId: PostRegionsRegionCountriesCountry
summary: Remove Country
description: Removes a Country from the list of Countries in a Region
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
- in: path
name: country_code
required: true
description: The 2 character ISO code for the Country.
schema:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
'/regions/{id}/fulfillment-providers/{provider_id}':
delete:
operationId: PostRegionsRegionFulfillmentProvidersProvider
summary: Remove Fulfillment Provider
description: Removes a Fulfillment Provider.
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
- in: path
name: provider_id
required: true
description: The id of the Fulfillment Provider.
schema:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
'/regions/{id}/payment-providers/{provider_id}':
delete:
operationId: PostRegionsRegionPaymentProvidersProvider
summary: Remove Payment Provider
description: Removes a Payment Provider.
parameters:
- in: path
name: id
required: true
description: The id of the Region.
schema:
type: string
- in: path
name: provider_id
required: true
description: The id of the Payment Provider.
schema:
type: string
tags:
- Region
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
region:
$ref: '#/components/schemas/region'
/returns:
get:
operationId: GetReturns
summary: List Returns
description: Retrieves a list of Returns
tags:
- Return
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
returns:
type: array
items:
$ref: '#/components/schemas/return'
/shipping-options:
post:
operationId: PostShippingOptions
summary: Create Shipping Option
description: Creates a Shipping Option
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Shipping Option
type: string
region_id:
description: >-
The id of the Region in which the Shipping Option will be
available.
type: string
provider_id:
description: >-
The id of the Fulfillment Provider that handles the Shipping
Option.
type: string
profile_id:
description: >-
The id of the Shipping Profile to add the Shipping Option
to.
type: number
data:
description: >-
The data needed for the Fulfillment Provider to handle
shipping with this Shipping Option.
type: object
price_type:
description: The type of the Shipping Option price.
type: string
enum:
- flat_rate
- calculated
amount:
description: The amount to charge for the Shipping Option.
type: integer
requirements:
description: >-
The requirements that must be satisfied for the Shipping
Option to be available.
type: array
items:
properties:
type:
description: The type of the requirement
type: string
enum:
- max_subtotal
- min_subtotal
amount:
description: The amount to compare with.
type: integer
is_return:
description: Whether the Shipping Option defines a return shipment.
type: boolean
tags:
- Shipping Option
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_option:
$ref: '#/components/schemas/shipping_option'
get:
operationId: GetShippingOptions
summary: List Shipping Options
description: Retrieves a list of Shipping Options.
tags:
- Shipping Option
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_options:
type: array
items:
$ref: '#/components/schemas/shipping_option'
'/shipping-options/{id}':
delete:
operationId: DeleteShippingOptionsOption
summary: Delete a Shipping Option
description: Deletes a Shipping Option.
parameters:
- in: path
name: id
required: true
description: The id of the Shipping Option.
schema:
type: string
tags:
- Shipping Option
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Shipping Option.
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetShippingOptionsOption
summary: Retrieve a Shipping Option
description: Retrieves a Shipping Option.
parameters:
- in: path
name: id
required: true
description: The id of the Shipping Option.
schema:
type: string
tags:
- Shipping Option
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_option:
$ref: '#/components/schemas/shipping_option'
post:
operationId: PostShippingOptionsOption
summary: Update Shipping Option
description: Updates a Shipping Option
parameters:
- in: path
name: id
required: true
description: The id of the Shipping Option.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Shipping Option
type: string
amount:
description: The amount to charge for the Shipping Option.
type: integer
requirements:
description: >-
The requirements that must be satisfied for the Shipping
Option to be available.
type: array
items:
properties:
type:
description: The type of the requirement
type: string
enum:
- max_subtotal
- min_subtotal
amount:
description: The amount to compare with.
type: integer
tags:
- Shipping Option
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_option:
$ref: '#/components/schemas/shipping_option'
/shipping-profiles:
post:
operationId: PostShippingProfiles
summary: Create a Shipping Profile
description: Creates a Shipping Profile
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Shipping Profile
type: string
tags:
- Shipping Profile
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_profile:
$ref: '#/components/schemas/shipping_profile'
get:
operationId: GetShippingProfiles
summary: List Shipping Profiles
description: Retrieves a list of Shipping Profile.
tags:
- Shipping Profile
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_profiles:
type: array
items:
$ref: '#/components/schemas/shipping_profile'
'/shipping-profiles/{id}':
delete:
operationId: DeleteShippingProfilesProfile
summary: Delete a Shipping Profile
description: Deletes a Shipping Profile.
parameters:
- in: path
name: id
required: true
description: The id of the Shipping Profile.
schema:
type: string
tags:
- Shipping Profile
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
id:
type: string
description: The id of the deleted Shipping Profile.
object:
type: string
description: The type of the object that was deleted.
deleted:
type: boolean
get:
operationId: GetShippingProfilesProfile
summary: Retrieve a Shipping Profile
description: Retrieves a Shipping Profile.
parameters:
- in: path
name: id
required: true
description: The id of the Shipping Profile.
schema:
type: string
tags:
- Shipping Profile
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_profile:
$ref: '#/components/schemas/shipping_profile'
post:
operationId: PostShippingProfilesProfile
summary: Update a Shipping Profiles
description: Updates a Shipping Profile
parameters:
- in: path
name: id
required: true
description: The id of the Shipping Profile.
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Shipping Profile
type: string
tags:
- Shipping Profile
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
shipping_profiles:
$ref: '#/components/schemas/shipping_profile'
'/store/currencies/{code}':
post:
operationId: PostStoreCurrenciesCode
summary: Add a Currency Code
description: Adds a Currency Code to the available currencies.
parameters:
- in: path
name: code
required: true
description: The 3 character ISO currency code.
schema:
type: string
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
store:
$ref: '#/components/schemas/store'
delete:
operationId: DeleteStoreCurrenciesCode
summary: Remvoe a Currency Code
description: Removes a Currency Code from the available currencies.
parameters:
- in: path
name: code
required: true
description: The 3 character ISO currency code.
schema:
type: string
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
store:
$ref: '#/components/schemas/store'
/store:
get:
operationId: GetStore
summary: Retrieve Store details.
description: Retrieves the Store details
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
store:
$ref: '#/components/schemas/store'
post:
operationId: PostStore
summary: Update Store details.
description: Updates the Store details
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name of the Store
type: string
swap_link_template:
description: >-
A template for Swap links - use `{{cart_id}}` to insert the
Swap Cart id
type: string
default_currency_code:
description: The default currency code for the Store.
type: string
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
store:
$ref: '#/components/schemas/store'
/store/payment-providers:
get:
operationId: GetStorePaymentProviders
summary: Retrieve configured Payment Providers
description: Retrieves the configured Payment Providers
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
payment_providers:
type: array
items:
$ref: '#/components/schemas/store'
/swaps:
get:
operationId: GetSwaps
summary: List Swaps
description: Retrieves a list of Swaps.
tags:
- Swap
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
swaps:
type: array
items:
$ref: '#/components/schemas/swap'
/variants:
get:
operationId: GetVariants
summary: List Product Variants.
description: Retrieves a list of Product Variants
tags:
- Product Variant
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
variants:
type: array
items:
$ref: '#/components/schemas/product_variant'
components:
schemas:
address:
title: Address
description: An address.
x-resourceId: address
properties:
id:
type: string
customer_id:
type: string
company:
type: string
first_name:
type: string
last_name:
type: string
address_1:
type: string
address_2:
type: string
city:
type: string
country_code:
type: string
country:
$ref: '#/components/schemas/country'
cart:
title: Cart
description: Represents a user cart
x-resourceId: cart
properties:
id:
type: string
email:
type: string
billing_address_id:
type: string
billing_address:
$ref: '#/components/schemas/address'
shipping_address_id:
type: string
shipping_address:
$ref: '#/components/schemas/address'
items:
type: array
items:
$ref: '#/components/schemas/line_item'
region_id:
type: string
region:
$ref: '#/components/schemas/region'
discounts:
type: array
items:
$ref: '#/components/schemas/region'
gift_cards:
type: array
items:
$ref: '#/components/schemas/gift_card'
customer_id:
type: string
customer:
$ref: '#/components/schemas/customer'
payment_session:
$ref: '#/components/schemas/payment_session'
payment_sessions:
type: array
items:
$ref: '#/components/schemas/payment_session'
payment:
$ref: '#/components/schemas/payment'
shipping_methods:
type: array
items:
$ref: '#/components/schemas/shipping_method'
type:
type: string
enum:
- default
- swap
- payment_link
completed_at:
type: string
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
shipping_total:
type: integer
discount_total:
type: integer
tax_total:
type: integer
subtotal:
type: integer
refundable_amount:
type: integer
gift_card_total:
type: integer
claim_image:
title: Claim Image
description: Represents photo documentation of a claim.
x-resourceId: claim_image
properties:
id:
type: string
claim_item_id:
type: string
url:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
claim_item:
title: Claim Item
description: >-
Represents a claimed item along with information about the reasons for
the claim.
x-resourceId: claim_item
properties:
id:
type: string
images:
type: array
items:
$ref: '#/components/schemas/claim_image'
claim_order_id:
type: string
item_id:
type: string
item:
description: The Line Item that the claim refers to
$ref: '#/components/schemas/line_item'
variant_id:
type: string
variant:
description: The Product Variant that is claimed.
$ref: '#/components/schemas/product_variant'
reason:
description: The reason for the claim
type: string
enum:
- missing_item
- wrong_item
- production_failure
- other
note:
description: 'An optional note about the claim, for additional information'
type: string
quantity:
description: >-
The quantity of the item that is being claimed; must be less than or
equal to the amount purchased in the original order.
type: integer
tags:
description: User defined tags for easy filtering and grouping.
type: array
items:
$ref: '#/components/schemas/claim_tag'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
claim_order:
title: Claim Order
description: >-
Claim Orders represent a group of faulty or missing items. Each claim
order consists of a subset of items associated with an original order,
and can contain additional information about fulfillments and returns.
x-resourceId: claim_order
properties:
id:
type: string
type:
type: string
enum:
- refund
- replace
payment_status:
type: string
enum:
- na
- not_refunded
- refunded
fulfillment_status:
type: string
enum:
- not_fulfilled
- partially_fulfilled
- fulfilled
- partially_shipped
- shipped
- partially_returned
- returned
- canceled
- requires_action
claim_items:
description: The items that have been claimed
type: array
items:
$ref: '#/components/schemas/claim_item'
additional_items:
description: >-
Refers to the new items to be shipped when the claim order has the
type `replace`
type: array
items:
$ref: '#/components/schemas/line_item'
order_id:
description: The id of the order that the claim comes from.
type: string
return_order:
description: Holds information about the return if the claim is to be returned
$ref: '#/components/schemas/return'
shipping_address_id:
description: The id of the address that the new items should be shipped to
type: string
shipping_address:
description: The address that the new items should be shipped to
$ref: '#/components/schemas/address'
shipping_methods:
description: The shipping methods that the claim order will be shipped with.
type: array
items:
$ref: '#/components/schemas/shipping_method'
fulfillments:
description: The fulfillments of the new items to be shipped
type: array
items:
$ref: '#/components/schemas/fulfillment'
refund_amount:
description: The amount that will be refunded in conjunction with the claim
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
claim_tag:
title: Claim Tag
description: >-
Claim Tags are user defined tags that can be assigned to claim items for
easy filtering and grouping.
x-resourceId: claim_tag
properties:
id:
description: The id of the claim tag. Will be prefixed by `ctag_`.
type: string
value:
description: The value that the claim tag holds
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
update_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
country:
title: Country
description: Country details
x-resourceId: country
properties:
id:
description: The database id of the country
type: integer
iso_2:
description: The 2 character ISO code for the country.
type: string
iso_3:
description: The 3 character ISO code for the country.
type: string
num_code:
description: The numerical ISO code for the country.
type: string
name:
description: The normalized country name; in upper case.
type: string
display_name:
description: The country name appropriate for display.
type: string
currency:
title: Currency
description: Currency
x-resourceId: currency
properties:
code:
description: The 3 character ISO code for the currency.
type: string
symbol:
description: The symbol used to indicate the currency.
type: string
symbol_native:
description: The native symbol used to indicate the currency.
type: string
name:
description: The written name of the currency
type: string
customer:
title: Customer
description: Represents a customer
x-resourceId: customer
properties:
id:
type: string
email:
type: string
billing_address_id:
type: string
billing_address:
description: The Customer's billing address.
anyOf:
- $ref: '#/components/schemas/address'
shipping_addresses:
type: array
items:
$ref: '#/components/schemas/address'
first_name:
type: string
last_name:
type: string
phone:
type: string
has_account:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
discount_rule:
title: Discount Rule
description: >-
Holds the rules that governs how a Discount is calculated when applied
to a Cart.
x-resourceId: discount_rule
properties:
id:
description: The id of the Discount Rule. Will be prefixed by `dru_`.
type: string
type:
description: >-
The type of the Discount, can be `fixed` for discounts that reduce
the price by a fixed amount, `percentage` for percentage reductions
or `free_shipping` for shipping vouchers.
type: string
enum:
- fixed
- percentage
- free_shipping
description:
description: A short description of the discount
type: string
value:
description: >-
The value that the discount represents; this will depend on the type
of the discount
type: integer
allocation:
description: The scope that the discount should apply to.
type: string
enum:
- total
- item
valid_for:
description: A set of Products that the discount can be used for.
type: array
items:
$ref: '#/components/schemas/product'
usage_limit:
description: The maximum number of times that a discount can be used.
type: integer
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
update_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
discount:
title: Discount
description: >-
Represents a discount that can be applied to a cart for promotional
purposes.
x-resourceId: discount
properties:
id:
description: The id of the Discount. Will be prefixed by `disc_`.
type: string
code:
description: >-
A unique code for the discount - this will be used by the customer
to apply the discount
type: string
is_dynamic:
description: >-
A flag to indicate if multiple instances of the discount can be
generated. I.e. for newsletter discounts
type: boolean
rule:
description: The Discount Rule that governs the behaviour of the Discount
anyOf:
- $ref: '#/components/schemas/discount_rule'
is_disabled:
description: >-
Whether the Discount has been disabled. Disabled discounts cannot be
applied to carts
type: boolean
parent_discount_id:
description: >-
The Discount that the discount was created from. This will always be
a dynamic discount
type: string
starts_at:
description: The time at which the discount can be used.
type: string
format: date-time
ends_at:
description: The time at which the discount can no longer be used.
type: string
format: date-time
regions:
description: The Regions in which the Discount can be used
type: array
items:
$ref: '#/components/schemas/region'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
fulfillment_item:
title: Fulfillment Item
description: >-
Correlates a Line Item with a Fulfillment, keeping track of the quantity
of the Line Item.
x-resourceId: fulfillment_item
properties:
fulfillment_id:
description: The id of the Fulfillment that the Fulfillment Item belongs to.
type: string
item_id:
description: The id of the Line Item that the Fulfillment Item references.
type: string
item:
description: The Line Item that the Fulfillment Item references.
anyOf:
- $ref: '#/components/schemas/line_item'
quantity:
description: The quantity of the Line Item that is included in the Fulfillment.
type: integer
fulfillment_provider:
title: Fulfillment Provider
description: >-
Represents a fulfillment provider plugin and holds its installation
status.
x-resourceId: fulfillment_provider
properties:
id:
description: The id of the fulfillment provider as given by the plugin.
type: string
is_installed:
description: >-
Whether the plugin is installed in the current version. Plugins that
are no longer installed are not deleted by will have this field set
to `false`.
type: boolean
fulfillment:
title: Fulfillment
description: >-
Fulfillments are created once store operators can prepare the purchased
goods. Fulfillments will eventually be shipped and hold information
about how to track shipments. Fulfillments are created through a
provider, which is typically an external shipping aggregator, shipping
partner og 3PL, most plugins will have asynchronous communications with
these providers through webhooks in order to automatically update and
synchronize the state of Fulfillments.
x-resourceId: fulfillment
properties:
id:
description: The id of the Fulfillment. This value will be prefixed by `ful_`.
type: string
claim_order_id:
description: The id of the Claim that the Fulfillment belongs to.
type: string
swap_id:
description: The id of the Swap that the Fulfillment belongs to.
type: string
order_id:
description: The id of the Order that the Fulfillment belongs to.
type: string
provider_id:
description: >-
The id of the Fulfillment Provider responsible for handling the
fulfillment
type: string
items:
description: >-
The Fulfillment Items in the Fulfillment - these hold information
about how many of each Line Item has been fulfilled.
type: array
items:
$ref: '#/components/schemas/fulfillment_item'
tracking_links:
description: >-
The Tracking Links that can be used to track the status of the
Fulfillment, these will usually be provided by the Fulfillment
Provider.
type: array
items:
$ref: '#/components/schemas/tracking_link'
tracking_numbers:
deprecated: true
description: >-
The tracking numbers that can be used to track the status of the
fulfillment.
type: array
items:
type: string
shipped_at:
description: The date with timezone at which the Fulfillment was shipped.
type: string
format: date-time
canceled_at:
description: The date with timezone at which the Fulfillment was canceled.
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
gift_card_transaction:
title: Gift Card Transaction
description: >-
Gift Card Transactions are created once a Customer uses a Gift Card to
pay for their Order
x-resourceId: gift_card_transaction
properties:
id:
description: >-
The id of the Gift Card Transaction. This value will be prefixed by
`gct_`.
type: string
gift_card_id:
description: The id of the Gift Card that was used in the transaction.
type: string
gift_card:
description: The Gift Card that was used in the transaction.
anyOf:
- $ref: '#/components/schemas/gift_card'
order_id:
description: The id of the Order that the Gift Card was used to pay for.
type: string
amount:
description: The amount that was used from the Gift Card.
type: integer
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
gift_card:
title: Gift Card
description: >-
Gift Cards are redeemable and represent a value that can be used towards
the payment of an Order.
x-resourceId: gift_card
properties:
id:
description: The id of the Gift Card. This value will be prefixed by `gift_`.
type: string
code:
description: >-
The unique code that identifies the Gift Card. This is used by the
Customer to redeem the value of the Gift Card.
type: string
value:
description: The value that the Gift Card represents.
type: integer
balance:
description: The remaining value on the Gift Card.
type: integer
region_id:
description: The id of the Region in which the Gift Card is available.
type: string
region:
description: The Region in which the Gift Card is available.
anyOf:
- $ref: '#/components/schemas/region'
order_id:
description: The id of the Order that the Gift Card was purchased in.
type: string
is_disabled:
description: >-
Whether the Gift Card has been disabled. Disabled Gift Cards cannot
be applied to carts.
type: boolean
ends_at:
description: The time at which the Gift Card can no longer be used.
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
image:
title: Image
description: Images holds a reference to a URL at which the image file can be found.
x-resourceId: image
properties:
id:
description: The id of the Image. This value will be prefixed by `img_`.
type: string
url:
description: The URL at which the image file can be found.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
update_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
line_item:
title: Line Item
description: >-
Line Items represent purchasable units that can be added to a Cart for
checkout. When Line Items are purchased they will get copied to the
resulting order and can eventually be referenced in Fulfillments and
Returns. Line Items may also be created when processing Swaps and
Claims.
x-resourceId: line_item
properties:
id:
description: The id of the Line Item. This value will be prefixed by `item_`.
type: string
cart_id:
description: The id of the Cart that the Line Item belongs to.
type: string
order_id:
description: The id of the Order that the Line Item belongs to.
type: string
swap_id:
description: The id of the Swap that the Line Item belongs to.
type: string
claim_order_id:
description: The id of the Claim that the Line Item belongs to.
type: string
title:
description: >-
The title of the Line Item, this should be easily identifiable by
the Customer.
type: string
description:
description: A more detailed description of the contents of the Line Item.
type: string
thumbnail:
description: A URL string to a small image of the contents of the Line Item.
type: string
is_giftcard:
description: Flag to indicate if the Line Item is a Gift Card.
type: boolean
should_merge:
description: >-
Flag to indicate if new Line Items with the same variant should be
merged or added as an additional Line Item.
type: boolean
allow_discounts:
description: >-
Flag to indicate if the Line Item should be included when doing
discount calculations.
type: boolean
unit_price:
description: >-
The price of one unit of the content in the Line Item. This should
be in the currency defined by the Cart/Order/Swap/Claim that the
Line Item belongs to.
type: boolean
variant_id:
description: The id of the Product Variant contained in the Line Item.
type: string
variant:
description: The Product Variant contained in the Line Item.
anyOf:
- $ref: '#/components/schemas/product_variant'
quantity:
description: The quantity of the content in the Line Item.
type: integer
fulfilled_quantity:
description: The quantity of the Line Item that has been fulfilled.
type: integer
returned_quantity:
description: The quantity of the Line Item that has been returned.
type: integer
shipped_quantity:
description: The quantity of the Line Item that has been shipped.
type: integer
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
refundable:
description: >-
The amount that can be refunded from the given Line Item. Takes
taxes and discounts into consideration.
type: integer
money_amount:
title: Money Amount
description: >-
Money Amounts represents an amount that a given Product Variant can be
purcased for. Each Money Amount either has a Currency or Region
associated with it to indicate the pricing in a given Currency or, for
fully region-based pricing, the given price in a specific Region. If
region-based pricing is used the amount will be in the currency defined
for the Reigon.
x-resourceId: money_amount
properties:
id:
description: The id of the Money Amount. This value will be prefixed by `ma_`.
type: string
currency_code:
description: The 3 character currency code that the Money Amount is given in.
type: string
amount:
description: >-
The amount in the smallest currecny unit (e.g. cents 100 cents to
charge $1) that the Product Variant will cost.
type: integer
sale_amount:
description: >-
An optional sale amount that the Product Variant will be available
for when defined.
type: integer
variant_id:
description: The id of the Product Variant that the Money Amount belongs to.
type: string
region_id:
description: The id of the Region that the Money Amount is defined for.
type: string
region:
description: The Region that the Money Amount is defined for.
anyOf:
- $ref: '#/components/schemas/region'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
notification_provider:
title: Notification Provider
description: >-
Represents a notification provider plugin and holds its installation
status.
x-resourceId: notification_provider
properties:
id:
description: The id of the notification provider as given by the plugin.
type: string
is_installed:
description: >-
Whether the plugin is installed in the current version. Plugins that
are no longer installed are not deleted by will have this field set
to `false`.
type: boolean
notification:
title: Notification
description: >-
Notifications a communications sent via Notification Providers as a
reaction to internal events such as `order.placed`. Notifications can be
used to show a chronological timeline for communications sent to a
Customer regarding an Order, and enables resends.
x-resourceId: notification
properties:
id:
description: The id of the Notification. This value will be prefixed by `noti_`.
type: string
event_name:
description: The name of the event that the notification was sent for.
type: string
resource_type:
description: The type of resource that the Notification refers to.
type: string
resource_id:
description: The id of the resource that the Notification refers to.
type: string
customer_id:
description: The id of the Customer that the Notification was sent to.
type: string
customer:
description: The Customer that the Notification was sent to.
anyOf:
- $ref: '#/components/schemas/customer'
to:
description: >-
The address that the Notification was sent to. This will usually be
an email address, but represent other addresses such as a chat bot
user id
type: string
data:
description: >-
The data that the Notification was sent with. This contains all the
data necessary for the Notification Provider to initiate a resend.
type: object
parent_id:
description: The id of the Notification that was originally sent.
type: string
resends:
description: >-
The resends that have been completed after the original
Notification.
type: array
items:
$ref: '#/components/schemas/notification_resend'
provider_id:
description: The id of the Notification Provider that handles the Notification.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
notification_resend:
title: Notification Resend
description: A resend of a Notification.
x-resourceId: notification_resend
properties:
id:
description: The id of the Notification. This value will be prefixed by `noti_`.
type: string
event_name:
description: The name of the event that the notification was sent for.
type: string
resource_type:
description: The type of resource that the Notification refers to.
type: string
resource_id:
description: The id of the resource that the Notification refers to.
type: string
to:
description: >-
The address that the Notification was sent to. This will usually be
an email address, but represent other addresses such as a chat bot
user id
type: string
data:
description: >-
The data that the Notification was sent with. This contains all the
data necessary for the Notification Provider to initiate a resend.
type: object
parent_id:
description: The id of the Notification that was originally sent.
type: string
provider_id:
description: The id of the Notification Provider that handles the Notification.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
order:
title: Order
description: Represents an order
x-resourceId: order
properties:
id:
type: string
status:
type: string
enum:
- pending
- completed
- archived
- canceled
- requires_action
fulfillment_status:
type: string
enum:
- not_fulfilled
- partially_fulfilled
- fulfilled
- partially_shipped
- shipped
- partially_returned
- returned
- canceled
- requires_action
payment_status:
type: string
enum:
- not_paid
- awaiting
- captured
- partially_refunded
- refuneded
- canceled
- requires_action
display_id:
type: integer
cart_id:
type: string
currency_code:
type: string
tax_rate:
type: integer
discounts:
type: array
items:
$ref: '#/components/schemas/discount'
email:
type: string
billing_address_id:
type: string
billing_address:
anyOf:
- $ref: '#/components/schemas/address'
shipping_address_id:
type: string
shipping_address:
anyOf:
- $ref: '#/components/schemas/address'
items:
type: array
items:
$ref: '#/components/schemas/line_item'
region_id:
type: string
region:
anyOf:
- $ref: '#/components/schemas/region'
gift_cards:
type: array
items:
$ref: '#/components/schemas/gift_card'
customer_id:
type: string
customer:
anyOf:
- $ref: '#/components/schemas/customer'
payment_session:
anyOf:
- $ref: '#/components/schemas/payment_session'
payment_sessions:
type: array
items:
$ref: '#/components/schemas/payment_session'
payments:
type: array
items:
$ref: '#/components/schemas/payment'
shipping_methods:
type: array
items:
$ref: '#/components/schemas/shipping_method'
fulfillments:
type: array
items:
$ref: '#/components/schemas/fulfillment'
returns:
type: array
items:
$ref: '#/components/schemas/return'
claims:
type: array
items:
$ref: '#/components/schemas/claim_order'
refunds:
type: array
items:
$ref: '#/components/schemas/refund'
swaps:
type: array
items:
$ref: '#/components/schemas/refund'
gift_card_transactions:
type: array
items:
$ref: '#/components/schemas/gift_card_transaction'
canceled_at:
type: string
format: date-time
created_at:
type: string
format: date-time
update_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
shipping_total:
type: integer
discount_total:
type: integer
tax_total:
type: integer
subtotal:
type: integer
refundable_amount:
type: integer
gift_card_total:
type: integer
payment_provider:
title: Payment Provider
description: Represents a Payment Provider plugin and holds its installation status.
x-resourceId: payment_provider
properties:
id:
description: The id of the payment provider as given by the plugin.
type: string
is_installed:
description: >-
Whether the plugin is installed in the current version. Plugins that
are no longer installed are not deleted by will have this field set
to `false`.
type: boolean
payment_session:
title: Payment Session
description: >-
Payment Sessions are created when a Customer initilizes the checkout
flow, and can be used to hold the state of a payment flow. Each Payment
Session is controlled by a Payment Provider, who is responsible for the
communication with external payment services. Authorized Payment
Sessions will eventually get promoted to Payments to indicate that they
are authorized for capture/refunds/etc.
x-resourceId: payment_session
properties:
id:
description: >-
The id of the Payment Session. This value will be prefixed with
`ps_`.
type: string
cart_id:
description: The id of the Cart that the Payment Session is created for.
type: string
provider_id:
description: >-
The id of the Payment Provider that is responsible for the Payment
Session
type: string
is_selected:
description: >-
A flag to indicate if the Payment Session has been selected as the
method that will be used to complete the purchase.
type: boolean
status:
description: >-
Indicates the status of the Payment Session. Will default to
`pending`, and will eventually become `authorized`. Payment Sessions
may have the status of `requires_more` to indicate that further
actions are to be completed by the Customer.
type: string
enum:
- authorized
- pending
- requires_more
- error
- canceled
data:
description: >-
The data required for the Payment Provider to identify, modify and
process the Payment Session. Typically this will be an object that
holds an id to the external payment session, but can be an empty
object if the Payment Provider doesn't hold any state.
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
payment:
title: Payment
description: >-
Payments represent an amount authorized with a given payment method,
Payments can be captured, canceled or refunded.
x-resourceId: payment
properties:
id:
description: The id of the Payment. This value will be prefixed with `pay_`.
type: string
swap_id:
description: The id of the Swap that the Payment is used for.
type: string
order_id:
description: The id of the Order that the Payment is used for.
type: string
cart_id:
description: The id of the Cart that the Payment Session is created for.
type: string
amount:
description: The amount that the Payment has been authorized for.
type: integer
currency_code:
description: The 3 character ISO currency code that the Payment is completed in.
type: string
amount_refunded:
description: >-
The amount of the original Payment amount that has been refunded
back to the Customer.
type: integer
provider_id:
description: The id of the Payment Provider that is responsible for the Payment
type: string
data:
description: >-
The data required for the Payment Provider to identify, modify and
process the Payment. Typically this will be an object that holds an
id to the external payment session, but can be an empty object if
the Payment Provider doesn't hold any state.
type: object
captured_at:
description: The date with timezone at which the Payment was captured.
type: string
format: date-time
canceled_at:
description: The date with timezone at which the Payment was canceled.
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product_collection:
title: Product Collection
description: Product Collections represents a group of Products that are related.
x-resourceId: product_collection
properties:
id:
description: >-
The id of the Product Collection. This value will be prefixed with
`pcol_`.
type: string
title:
description: The title that the Product Collection is identified by.
type: string
handle:
description: >-
A unique string that identifies the Product Collection - can for
example be used in slug structures.
type: string
products:
description: The Products contained in the Product Collection.
type: array
items:
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product_option_value:
title: Product Option Value
description: >-
A value given to a Product Variant's option set. Product Variant have a
Product Option Value for each of the Product Options defined on the
Product.
x-resourceId: product_option_value
properties:
id:
description: >-
The id of the Product Option Value. This value will be prefixed with
`optval_`.
type: string
value:
description: >-
The value that the Product Variant has defined for the specific
Product Option (e.g. if the Product Option is "Size" this value
could be "Small", "Medium" or "Large").
type: string
option_id:
description: >-
The id of the Product Option that the Product Option Value is
defined for.
type: string
variant_id:
description: >-
The id of the Product Variant that the Product Option Value is
defined for.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product_option:
title: Product Option
description: >-
Product Options define properties that may vary between different
variants of a Product. Common Product Options are "Size" and "Color",
but Medusa doesn't limit what Product Options that can be defined.
x-resourceId: product_option
properties:
id:
description: >-
The id of the Product Option. This value will be prefixed with
`opt_`.
type: string
title:
description: The title that the Product Option is defined by (e.g. "Size").
type: string
values:
description: The Product Option Values that are defined for the Product Option.
type: array
items:
$ref: '#/components/schemas/product_option_value'
product_id:
description: The id of the Product that the Product Option is defined for.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product_tag:
title: Product Tag
description: Product Tags can be added to Products for easy filtering and grouping.
x-resourceId: product_tag
properties:
id:
description: The id of the Product Tag. This value will be prefixed with `ptag_`.
type: string
value:
description: The value that the Product Tag represents (e.g. "Pants").
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product_type:
title: Product Type
description: >-
Product Type can be added to Products for filtering and reporting
purposes.
x-resourceId: product_type
properties:
id:
description: >-
The id of the Product Type. This value will be prefixed with
`ptyp_`.
type: string
value:
description: The value that the Product Type represents (e.g. "Clothing").
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product_variant:
title: Product Variant
description: >-
Product Variants represent a Product with a specific set of Product
Option configurations. The maximum number of Product Variants that a
Product can have is given by the number of available Product Option
combinations.
x-resourceId: product_variant
properties:
id:
description: >-
The id of the Product Variant. This value will be prefixed with
`variant_`.
type: string
title:
description: >-
A title that can be displayed for easy identification of the Product
Variant.
type: string
product_id:
description: The id of the Product that the Product Variant belongs to.
type: string
prices:
description: >-
The Money Amounts defined for the Product Variant. Each Money Amount
represents a price in a given currency or a price in a specific
Region.
type: array
items:
$ref: '#/components/schemas/money_amount'
sku:
description: >-
The unique stock keeping unit used to identify the Product Variant.
This will usually be a unqiue identifer for the item that is to be
shipped, and can be referenced across multiple systems.
type: string
barcode:
description: >-
A generic field for a GTIN number that can be used to identify the
Product Variant.
type: string
ean:
description: >-
An EAN barcode number that can be used to identify the Product
Variant.
type: string
upc:
description: >-
A UPC barcode number that can be used to identify the Product
Variant.
type: string
inventory_quantity:
description: The current quantity of the item that is stocked.
type: integer
allow_backorder:
description: >-
Whether the Product Variant should be purchasable when
`inventory_quantity` is 0.
type: boolean
manage_inventory:
description: Whether Medusa should manage inventory for the Product Variant.
type: boolean
hs_code:
description: >-
The Harmonized System code of the Product Variant. May be used by
Fulfillment Providers to pass customs information to shipping
carriers.
type: string
origin_country:
description: >-
The country in which the Product Variant was produced. May be used
by Fulfillment Providers to pass customs information to shipping
carriers.
type: string
mid_code:
description: >-
The Manufacturers Identification code that identifies the
manufacturer of the Product Variant. May be used by Fulfillment
Providers to pass customs information to shipping carriers.
type: string
material:
description: >-
The material and composition that the Product Variant is made of,
May be used by Fulfillment Providers to pass customs information to
shipping carriers.
type: string
weight:
description: >-
The weight of the Product Variant. May be used in shipping rate
calculations.
type: string
height:
description: >-
The height of the Product Variant. May be used in shipping rate
calculations.
type: string
width:
description: >-
The width of the Product Variant. May be used in shipping rate
calculations.
type: string
length:
description: >-
The length of the Product Variant. May be used in shipping rate
calculations.
type: string
options:
description: The Product Option Values specified for the Product Variant.
type: array
items:
$ref: '#/components/schemas/product_option_value'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
product:
title: Product
description: >-
Products are a grouping of Product Variants that have common properties
such as images and descriptions. Products can have multiple options
which define the properties that Product Variants differ by.
x-resourceId: product
properties:
id:
description: The id of the Product. This value will be prefixed with `prod_`.
type: string
title:
description: >-
A title that can be displayed for easy identification of the
Product.
type: string
subtitle:
description: >-
An optional subtitle that can be used to further specify the
Product.
type: string
description:
description: A short description of the Product.
type: string
handle:
description: A unique identifier for the Product (e.g. for slug structure).
type: string
is_giftcard:
description: >-
Whether the Product represents a Gift Card. Products that represent
Gift Cards will automatically generate a redeemable Gift Card code
once they are purchased.
type: boolean
images:
description: Images of the Product
type: array
items:
$ref: '#/components/schemas/image'
thumbnail:
description: A URL to an image file that can be used to identify the Product.
type: string
options:
description: >-
The Product Options that are defined for the Product. Product
Variants of the Product will have a unique combination of Product
Option Values.
type: array
items:
$ref: '#/components/schemas/product_option'
variants:
description: >-
The Product Variants that belong to the Product. Each will have a
unique combination of Product Option Values.
type: array
items:
$ref: '#/components/schemas/product_variant'
profile_id:
description: >-
The id of the Shipping Profile that the Product belongs to. Shipping
Profiles have a set of defined Shipping Options that can be used to
Fulfill a given set of Products.
type: string
hs_code:
description: >-
The Harmonized System code of the Product Variant. May be used by
Fulfillment Providers to pass customs information to shipping
carriers.
type: string
origin_country:
description: >-
The country in which the Product Variant was produced. May be used
by Fulfillment Providers to pass customs information to shipping
carriers.
type: string
mid_code:
description: >-
The Manufacturers Identification code that identifies the
manufacturer of the Product Variant. May be used by Fulfillment
Providers to pass customs information to shipping carriers.
type: string
material:
description: >-
The material and composition that the Product Variant is made of,
May be used by Fulfillment Providers to pass customs information to
shipping carriers.
type: string
weight:
description: >-
The weight of the Product Variant. May be used in shipping rate
calculations.
type: string
height:
description: >-
The height of the Product Variant. May be used in shipping rate
calculations.
type: string
width:
description: >-
The width of the Product Variant. May be used in shipping rate
calculations.
type: string
length:
description: >-
The length of the Product Variant. May be used in shipping rate
calculations.
type: string
type:
description: The Product Type of the Product (e.g. "Clothing")
anyOf:
- $ref: '#/components/schemas/product_type'
collection:
description: The Product Collection that the Product belongs to (e.g. "SS20")
anyOf:
- $ref: '#/components/schemas/product_collection'
tags:
description: The Product Tags assigned to the Product.
type: array
items:
$ref: '#/components/schemas/product_tag'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
refund:
title: Refund
description: >-
Refund represent an amount of money transfered back to the Customer for
a given reason. Refunds may occur in relation to Returns, Swaps and
Claims, but can also be initiated by a store operator.
x-resourceId: refund
properties:
id:
description: The id of the Refund. This value will be prefixed with `ref_`.
type: string
order_id:
description: The id of the Order that the Refund is related to.
type: string
amount:
description: The amount that has be refunded to the Customer.
type: integer
note:
description: An optional note explaining why the amount was refunded.
type: string
reason:
description: >-
The reason given for the Refund, will automatically be set when
processed as part of a Swap, Claim or Return.
type: string
enum:
- discount
- return
- swap
- claim
- other
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
region:
title: Region
description: >-
Regions hold settings for how Customers in a given geographical location
shop. The is, for example, where currencies and tax rates are defined. A
Region can consist of multiple countries to accomodate common shopping
settings across countries.
x-resourceId: region
properties:
id:
description: The id of the Region. This value will be prefixed with `reg_`.
type: string
name:
description: >-
The name of the region as displayed to the customer. If the Region
only has one country it is recommended to write the country name.
type: string
currency_code:
description: >-
The 3 character ISO currency code that Customers will shop in in the
Region.
type: string
tax_rate:
description: The tax rate that should be charged on purchases in the Region.
type: number
tax_code:
description: >-
The tax code used on purchases in the Region. This may be used by
other systems for accounting purposes.
type: string
countries:
description: The countries that are included in the Region.
type: array
items:
$ref: '#/components/schemas/country'
payment_providers:
description: >-
The Payment Providers that can be used to process Payments in the
Region.
type: array
items:
$ref: '#/components/schemas/payment_provider'
fulfillment_providers:
description: >-
The Fulfillment Providers that can be used to fulfill orders in the
Region.
type: array
items:
$ref: '#/components/schemas/fulfillment_provider'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
return_item:
title: Return Item
description: >-
Correlates a Line Item with a Return, keeping track of the quantity of
the Line Item that will be returned.
x-resourceId: return_item
properties:
return_id:
description: The id of the Return that the Return Item belongs to.
type: string
item_id:
description: The id of the Line Item that the Return Item references.
type: string
item:
description: The Line Item that the Return Item references.
anyOf:
- $ref: '#/components/schemas/line_item'
quantity:
description: The quantity of the Line Item that is included in the Return.
type: integer
is_requested:
description: >-
Whether the Return Item was requested initially or received
unexpectedly in the warehouse.
type: boolean
requested_quantity:
description: The quantity that was originally requested to be returned.
type: integer
recieved_quantity:
description: The quantity that was received in the warehouse.
type: integer
metadata:
description: An optional key-value map with additional information.
type: object
return:
title: Return
description: >-
Return orders hold information about Line Items that a Customer wishes
to send back, along with how the items will be returned. Returns can be
used as part of a Swap.
x-resourceId: return
properties:
id:
description: The id of the Return. This value will be prefixed with `ret_`.
type: string
status:
description: Status of the Return.
type: string
enum:
- requested
- received
- requires_action
items:
description: >-
The Return Items that will be shipped back to the warehouse. type:
array items: $ref:
swap_id:
description: The id of the Swap that the Return is a part of.
type: string
order_id:
description: The id of the Order that the Return is made from.
type: string
claim_order_id:
description: The id of the Claim that the Return is a part of.
type: string
shipping_method:
description: >-
The Shipping Method that will be used to send the Return back. Can
be null if the Customer facilitates the return shipment themselves.
anyOf:
- $ref: '#/components/schemas/shipping_method'
shipping_data:
description: >-
Data about the return shipment as provided by the Fulfilment
Provider that handles the return shipment.
type: object
refund_amount:
description: The amount that should be refunded as a result of the return.
type: integer
received_at:
description: The date with timezone at which the return was received.
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
shipping_method:
title: Shipping Method
description: >-
Shipping Methods represent a way in which an Order or Return can be
shipped. Shipping Methods are built from a Shipping Option, but may
contain additional details, that can be necessary for the Fulfillment
Provider to handle the shipment.
x-resourceId: shipping_method
properties:
id:
description: >-
The id of the Shipping Method. This value will be prefixed with
`sm_`.
type: string
shipping_option_id:
description: >-
The id of the Shipping Option that the Shipping Method is built
from.
type: string
shipping_option:
description: The Shipping Option that the Shipping Method is built from.
anyOf:
- $ref: '#/components/schemas/shipping_option'
order_id:
description: The id of the Order that the Shipping Method is used on.
type: string
return_id:
description: The id of the Return that the Shipping Method is used on.
type: string
swap_id:
description: The id of the Swap that the Shipping Method is used on.
type: string
cart_id:
description: The id of the Cart that the Shipping Method is used on.
type: string
claim_order_id:
description: The id of the Claim that the Shipping Method is used on.
type: string
price:
description: >-
The amount to charge for the Shipping Method. The currency of the
price is defined by the Region that the Order that the Shipping
Method belongs to is a part of.
type: integer
data:
description: >-
Additional data that the Fulfillment Provider needs to fulfill the
shipment. This is used in combination with the Shipping Options
data, and may contain information such as a drop point id.
type: object
shipping_option_requirement:
title: Shipping Option Requirement
description: >-
A requirement that a Cart must satisfy for the Shipping Option to be
available to the Cart.
x-resourceId: shipping_option_requirement
properties:
id:
description: >-
The id of the Shipping Option Requirement. This value will be
prefixed with `sor_`.
type: string
shipping_option_id:
description: >-
The id of the Shipping Option that the Shipping Option Requirement
belongs to.
type: string
type:
description: >-
The type of the requirement, this defines how the value will be
compared to the Cart's total. `min_subtotal` requirements define the
minimum subtotal that is needed for the Shipping Option to be
available, while the `max_subtotal` defines the maximum subtotal
that the Cart can have for the Shipping Option to be available.
type: string
enum:
- min_subtotal
- max_subtotal
amount:
description: The amount to compare the Cart subtotal to.
type: integer
shipping_option:
title: Shipping Option
description: >-
Shipping Options represent a way in which an Order or Return can be
shipped. Shipping Options have an associated Fulfillment Provider that
will be used when the fulfillment of an Order is initiated. Shipping
Options themselves cannot be added to Carts, but serve as a template for
Shipping Methods. This distinction makes it possible to customize
individual Shipping Methods with additional information.
x-resourceId: shipping_option
properties:
id:
description: >-
The id of the Shipping Option. This value will be prefixed with
`so_`.
type: string
name:
description: >-
The name given to the Shipping Option - this may be displayed to the
Customer.
type: string
region_id:
description: The id of the Region that the Shipping Option belongs to.
type: string
region:
description: The id of the Region that the Shipping Option belongs to.
anyOf:
- $ref: '#/components/schemas/region'
profile_id:
description: >-
The id of the Shipping Profile that the Shipping Option belongs to.
Shipping Profiles have a set of defined Shipping Options that can be
used to Fulfill a given set of Products.
type: string
provider_id:
description: >-
The id of the Fulfillment Provider, that will be used to process
Fulfillments from the Shipping Option.
type: string
price_type:
description: >-
The type of pricing calculation that is used when creatin Shipping
Methods from the Shipping Option. Can be `flat_rate` for fixed
prices or `calculated` if the Fulfillment Provider can provide price
calulations.
type: string
enum:
- flat_rate
- calculated
amount:
description: >-
The amount to charge for shipping when the Shipping Option price
type is `flat_rate`.
type: integer
is_return:
description: >-
Flag to indicate if the Shipping Option can be used for Return
shipments.
type: boolean
requirements:
description: >-
The requirements that must be satisfied for the Shipping Option to
be available for a Cart.
type: array
items:
$ref: '#/components/schemas/shipping_option_requirement'
data:
description: >-
The data needed for the Fulfillment Provider to identify the
Shipping Option.
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
shipping_profile:
title: Shipping Profile
description: >-
Shipping Profiles have a set of defined Shipping Options that can be
used to fulfill a given set of Products.
x-resourceId: shipping_profile
properties:
id:
description: >-
The id of the Shipping Profile. This value will be prefixed with
`sp_`.
type: string
name:
description: >-
The name given to the Shipping profile - this may be displayed to
the Customer.
type: string
type:
description: >-
The type of the Shipping Profile, may be `default`, `gift_card` or
`custom`.
type: string
enum:
- default
- gift_card
- custom
products:
description: The Products that the Shipping Profile defines Shipping Options for.
type: array
items:
$ref: '#/components/schemas/product'
shipping_options:
description: >-
The Shipping Options that can be used to fulfill the Products in the
Shipping Profile.
type: array
items:
anyOf:
- $ref: '#/components/schemas/shipping_option'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
store:
title: Store
description: 'Holds settings for the Store, such as name, currencies, etc.'
x-resourceId: store
properties:
id:
description: The id of the Store. This value will be prefixed with `store_`.
type: string
name:
description: The name of the Store - this may be displayed to the Customer.
type: string
default_currency_code:
description: >-
The default currency code used when no other currency code is
specified.
type: string
currencies:
description: The currencies that are enabled for the Store.
type: array
items:
$ref: '#/components/schemas/currency'
swap_link_template:
description: >-
A template to generate Swap links from use {{cart_id}} to include
the Swap's `cart_id` in the link.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
swap:
title: Swap
description: >-
Swaps can be created when a Customer wishes to exchange Products that
they have purchased to different Products. Swaps consist of a Return of
previously purchased Products and a Fulfillment of new Products, the
amount paid for the Products being returned will be used towards payment
for the new Products. In the case where the amount paid for the the
Products being returned exceed the amount to be paid for the new
Products, a Refund will be issued for the difference.
x-resourceId: swap
properties:
id:
description: The id of the Swap. This value will be prefixed with `swap_`.
type: string
fulfillment_status:
description: The status of the Fulfillment of the Swap.
type: string
enum:
- not_fulfilled
- partially_fulfilled
- fulfilled
- partially_shipped
- shipped
- partially_returned
- returned
- canceled
- requires_action
payment_status:
description: >-
The status of the Payment of the Swap. The payment may either refer
to the refund of an amount or the authorization of a new amount.
type: string
enum:
- not_paid
- awaiting
- captured
- canceled
- difference_refunded
- requires_action
order_id:
description: >-
The id of the Order where the Line Items to be returned where
purchased.
type: string
additional_items:
description: The new Line Items to ship to the Customer.
type: array
items:
$ref: '#/components/schemas/line_item'
return_order:
description: The Return that is issued for the return part of the Swap.
anyOf:
- $ref: '#/components/schemas/return'
fulfillments:
description: The Fulfillments used to send the new Line Items.
type: array
items:
$ref: '#/components/schemas/fulfillment'
payment:
description: >-
The Payment authorized when the Swap requires an additional amount
to be charged from the Customer.
anyOf:
- $ref: '#/components/schemas/payment'
difference_due:
description: >-
The difference that is paid or refunded as a result of the Swap. May
be negative when the amount paid for the returned items exceed the
total of the new Products.
type: integer
shipping_address:
description: >-
The Address to send the new Line Items to - in most cases this will
be the same as the shipping address on the Order.
anyOf:
- $ref: '#/components/schemas/address'
shipping_methods:
description: The Shipping Methods used to fulfill the addtional items purchased.
type: array
items:
$ref: '#/components/schemas/shipping_method'
cart_id:
description: The id of the Cart that the Customer will use to confirm the Swap.
type: string
confirmed_at:
description: >-
The date with timezone at which the Swap was confirmed by the
Customer.
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
tracking_link:
title: Tracking Link
description: >-
Tracking Link holds information about tracking numbers for a
Fulfillment. Tracking Links can optionally contain a URL that can be
visited to see the status of the shipment.
x-resourceId: tracking_link
properties:
id:
description: >-
The id of the Tracking Link. This value will be prefixed with
`tlink_`.
type: string
url:
description: The URL at which the status of the shipment can be tracked.
type: string
tracking_number:
description: The tracking number given by the shipping carrier.
type: string
fulfillment_id:
description: The id of the Fulfillment that the Tracking Link references.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
type: string
format: date-time
metadata:
description: An optional key-value map with additional information.
type: object
user:
title: User
description: Represents a User who can manage store settings.
x-resourceId: user
properties:
id:
description: The unique id of the User. This will be prefixed with `usr_`
type: string
email:
description: The email of the User
type: string
first_name:
type: string
last_name:
description: The Customer's billing address.
anyOf:
- $ref: '#/components/schemas/address'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
deleted_at:
type: string
format: date-time
metadata:
type: object
Reference in New Issue View Git Blame Copy Permalink