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: user: $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: user: $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 Order. 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 a list of Orders tags: - Order responses: '200': description: OK content: application/json: schema: properties: orders: type: array items: $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 reason_id: description: The id of the Return Reason to use. type: string note: description: An optional note with information about the Return. 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' /return-reasons: post: operationId: PostReturnReasons summary: Create a Return Reason description: Creates a Return Reason requestBody: content: application/json: schema: properties: label: description: The label to display to the Customer. type: string value: description: >- The value that the Return Reason will be identified by. Must be unique. type: string description: description: An optional description to for the Reason. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reason: $ref: '#/components/schemas/return_reason' get: operationId: GetReturnReasons summary: List Return Reasons description: Retrieves a list of Return Reasons. tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reasons: type: array items: $ref: '#/components/schemas/return_reason' '/return-reasons/{id}': get: operationId: GetReturnReasonsReason summary: Retrieve a Return Reason description: Retrieves a Return Reason. parameters: - in: path name: id required: true description: The id of the Return Reason. schema: type: string tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reason: $ref: '#/components/schemas/return_reason' post: operationId: PostReturnReasonsReason summary: Update a Return Reason description: Updates a Return Reason parameters: - in: path name: id required: true description: The id of the Return Reason. schema: type: string requestBody: content: application/json: schema: properties: label: description: The label to display to the Customer. type: string value: description: >- The value that the Return Reason will be identified by. Must be unique. type: string description: description: An optional description to for the Reason. type: string metadata: description: >- An optional set of key-value pairs with additional information. type: object tags: - Return Reason responses: '200': description: OK content: application/json: schema: properties: return_reason: $ref: '#/components/schemas/return_reason' /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 reason: description: The reason for returning the item. anyOf: - $ref: '#/components/schemas/return_reason' note: description: An optional note with additional details about the Return. type: string metadata: description: An optional key-value map with additional information. type: object return_reason: title: Return Reason description: >- A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned. x-resourceId: return_reason properties: id: description: The id of the Return Reason will start with `rr_`. type: string description: description: A description of the Reason. type: string label: description: A text that can be displayed to the Customer as a reason. type: string value: description: The value to identify the reason by. 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 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