{
  "openapi": "3.1.0",
  "info": {
    "title": "Purple Dot Private API",
    "description": "Server-to-server access to your Purple Dot data. Send your store's private access token in the `X-Purple-Dot-Access-Token` header. Successful responses are `{ meta: { result: \"success\" }, data }`; errors are `{ meta: { error, errorData }, data: {} }`.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://www.purpledotprice.com/admin/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "/waitlists",
      "x-page-title": "/waitlists"
    },
    {
      "name": "/planned_inventory",
      "x-page-title": "/planned_inventory"
    },
    {
      "name": "/pre-orders",
      "x-page-title": "/pre-orders"
    },
    {
      "name": "/pre-orders/count",
      "x-page-title": "/pre-orders/count"
    },
    {
      "name": "/pre-orders/count-units/sku/:sku",
      "x-page-title": "/pre-orders/count-units/sku/:sku"
    },
    {
      "name": "/inventory",
      "x-page-title": "/inventory"
    },
    {
      "name": "/fulfillment-orders",
      "x-page-title": "/fulfillment-orders"
    },
    {
      "name": "/fulfillment-orders/:id",
      "x-page-title": "/fulfillment-orders/:id"
    },
    {
      "name": "/fulfillment",
      "x-page-title": "/fulfillment"
    },
    {
      "name": "/refund",
      "x-page-title": "/refund"
    }
  ],
  "components": {
    "securitySchemes": {
      "accessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Purple-Dot-Access-Token",
        "description": "Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."
      }
    },
    "schemas": {
      "AuthErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Missing attribute: sku"
          }
        },
        "required": [
          "error"
        ]
      },
      "Waitlist": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "a2aecc56-ce64-49da-8ce6-099e664d85fd"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the Waitlist was created.",
            "example": "2023-10-27T14:44:09.726Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the Waitlist was last updated.",
            "example": "2023-11-02T09:12:41.203Z"
          },
          "earliest_ship_date": {
            "type": "string",
            "format": "date-time",
            "description": "The earliest ship date.",
            "example": "2023-11-25T05:00:00.000Z"
          },
          "latest_ship_date": {
            "type": "string",
            "format": "date-time",
            "description": "The latest ship date.",
            "example": "2023-12-10T04:59:59.999Z"
          },
          "state": {
            "type": "string",
            "enum": [
              "Live",
              "Paused",
              "Closed",
              "Scheduled",
              "Draft"
            ],
            "description": "The Waitlist’s state.",
            "example": "Live"
          },
          "launch_date": {
            "type": [
              "string",
              "null"
            ],
            "example": "2023-10-27T00:00:00.000Z"
          },
          "scheduled_pause_date": {
            "type": [
              "string",
              "null"
            ],
            "example": "2023-11-20T00:00:00.000Z"
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string",
              "example": "holiday"
            }
          },
          "availability": {
            "type": "object",
            "properties": {
              "product": {
                "type": "object",
                "properties": {
                  "product_id": {
                    "type": "string",
                    "example": "7257265143861"
                  },
                  "buy_size": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "example": 10
                  },
                  "committed": {
                    "type": "number",
                    "description": "Units sold.",
                    "example": 3
                  },
                  "available": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Units still available. `null` for variant-level figures a per-product Waitlist does not allocate.",
                    "example": 7
                  }
                },
                "required": [
                  "product_id",
                  "buy_size",
                  "committed",
                  "available"
                ]
              },
              "variants": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "variant_id": {
                      "type": "string",
                      "example": "42662551519285"
                    },
                    "sku": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "example": "ZTEST"
                    },
                    "buy_size": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "example": 10
                    },
                    "committed": {
                      "type": "number",
                      "description": "Units sold.",
                      "example": 3
                    },
                    "available": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Units still available. `null` for variant-level figures a per-product Waitlist does not allocate.",
                      "example": 7
                    }
                  },
                  "required": [
                    "variant_id",
                    "sku",
                    "buy_size",
                    "committed",
                    "available"
                  ]
                }
              }
            },
            "required": [
              "product",
              "variants"
            ]
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "earliest_ship_date",
          "latest_ship_date",
          "state",
          "launch_date",
          "scheduled_pause_date",
          "labels",
          "availability"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message."
              },
              "errorData": {
                "type": "object",
                "additionalProperties": {},
                "description": "Structured detail about the error."
              }
            },
            "required": [
              "error",
              "errorData"
            ]
          },
          "data": {
            "type": "object",
            "properties": {}
          }
        },
        "required": [
          "meta",
          "data"
        ]
      },
      "WaitlistSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "product_id": {
            "type": "string",
            "example": "7257265143861"
          },
          "state": {
            "type": "string",
            "example": "OPEN"
          },
          "earliest_ship_date": {
            "type": "string",
            "example": "2025-03-01T00:00:00Z"
          },
          "latest_ship_date": {
            "type": "string",
            "example": "2025-03-15T00:00:00Z"
          },
          "max_units": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sku_id": {
                  "type": "string",
                  "example": "42662551519285"
                },
                "max_units": {
                  "type": "number",
                  "example": 50
                }
              },
              "required": [
                "sku_id",
                "max_units"
              ]
            }
          }
        },
        "required": [
          "id",
          "product_id",
          "state",
          "earliest_ship_date",
          "latest_ship_date",
          "max_units"
        ]
      },
      "WaitlistRequest": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "minLength": 1,
            "description": "The product ID in the connected store.",
            "example": "7257265143861"
          },
          "earliest_ship_date": {
            "type": "string",
            "description": "The earliest ship date, as an ISO 8601 date or timestamp.",
            "example": "2025-03-01"
          },
          "latest_ship_date": {
            "type": "string",
            "description": "The latest ship date, as an ISO 8601 date or timestamp.",
            "example": "2025-03-15"
          },
          "max_units": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sku_id": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The external SKU (variant) ID.",
                  "example": "42662551519285"
                },
                "max_units": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Maximum units for this SKU.",
                  "example": 50
                }
              },
              "required": [
                "sku_id",
                "max_units"
              ]
            },
            "minItems": 1,
            "description": "The unit limit for each SKU on the Waitlist."
          },
          "state": {
            "type": "string",
            "enum": [
              "DRAFT",
              "OPEN",
              "PAUSED",
              "CLOSED"
            ],
            "example": "OPEN"
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string",
              "example": "spring-2025"
            }
          }
        },
        "required": [
          "product_id",
          "earliest_ship_date",
          "latest_ship_date",
          "max_units",
          "state",
          "labels"
        ]
      },
      "Pre-order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Purple Dot ID of the pre-order.",
            "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
          },
          "order_number": {
            "type": "string",
            "example": "2850312"
          },
          "reference": {
            "type": "string",
            "description": "Order reference shared with shoppers.",
            "example": "#PD2850312"
          },
          "cancel_reason": {
            "type": [
              "string",
              "null"
            ],
            "example": "customer"
          },
          "cancelled_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the whole order was cancelled, or `null`.",
            "example": "2024-11-14T16:20:39.796Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the pre-order was placed.",
            "example": "2024-11-14T16:18:25.635Z"
          },
          "placed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the pre-order was placed.",
            "example": "2024-11-14T16:18:25.635Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the pre-order was last updated.",
            "example": "2024-11-14T16:23:02.118Z"
          },
          "currency": {
            "type": "string",
            "description": "Presentment currency.",
            "example": "USD"
          },
          "email": {
            "type": "string",
            "example": "test@getpurpledot.com"
          },
          "customer": {
            "type": "object",
            "properties": {
              "external_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The platform customer ID, if known.",
                "example": "7287702192181"
              },
              "email": {
                "type": "string",
                "example": "test@getpurpledot.com"
              }
            },
            "required": [
              "external_id",
              "email"
            ]
          },
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
                },
                "name": {
                  "type": "string",
                  "example": "Test Product 1"
                },
                "sku": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "PS4-GRVN"
                },
                "product_id": {
                  "type": "string",
                  "example": "6914583167029"
                },
                "variant_id": {
                  "type": "string",
                  "example": "41125120573493"
                },
                "waitlist_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uuid",
                  "example": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec"
                },
                "quantity": {
                  "type": "integer",
                  "example": 1
                },
                "price": {
                  "type": "number",
                  "description": "Unit price.",
                  "example": 39.99
                },
                "total": {
                  "type": "number",
                  "example": 26.01
                },
                "total_discount": {
                  "type": "number",
                  "example": 16.1
                },
                "discount_allocations": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "example": 16.1
                      },
                      "discount_application_index": {
                        "type": "integer",
                        "example": 0
                      }
                    },
                    "required": [
                      "amount",
                      "discount_application_index"
                    ]
                  }
                },
                "taxable": {
                  "type": "boolean",
                  "example": true
                },
                "tax_lines": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "price": {
                        "type": "number",
                        "description": "Total tax amount.",
                        "example": 2.12
                      },
                      "rate": {
                        "type": "number",
                        "description": "Tax rate as a decimal.",
                        "example": 0.08875
                      },
                      "title": {
                        "type": "string",
                        "description": "Name of the tax.",
                        "example": "SALES_TAX"
                      },
                      "inclusive": {
                        "type": "boolean",
                        "description": "Whether the tax is already in the price.",
                        "example": false
                      }
                    },
                    "required": [
                      "price",
                      "rate",
                      "title",
                      "inclusive"
                    ]
                  }
                }
              },
              "required": [
                "id",
                "name",
                "sku",
                "product_id",
                "variant_id",
                "waitlist_id",
                "quantity",
                "price",
                "total",
                "total_discount",
                "discount_allocations",
                "taxable",
                "tax_lines"
              ]
            }
          },
          "shipping_address": {
            "type": "object",
            "properties": {
              "first_name": {
                "type": "string",
                "example": "Test"
              },
              "last_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Testington"
              },
              "address1": {
                "type": "string",
                "example": "10 Test Road"
              },
              "address2": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Apt 4B"
              },
              "city": {
                "type": "string",
                "example": "New York"
              },
              "postal_code": {
                "type": "string",
                "example": "10463"
              },
              "province_code": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "NY"
              },
              "country": {
                "type": "string",
                "example": "United States"
              },
              "country_code": {
                "type": "string",
                "example": "US"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "+19172756975"
              }
            },
            "required": [
              "first_name",
              "last_name",
              "address1",
              "address2",
              "city",
              "postal_code",
              "province_code",
              "country",
              "country_code",
              "phone"
            ]
          },
          "shipping_lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "usps_1058"
                },
                "title": {
                  "type": "string",
                  "example": "Calculated Shipping Rate"
                },
                "price": {
                  "type": "number",
                  "example": 5.98
                },
                "total": {
                  "type": "number",
                  "example": 3.88
                },
                "tax_lines": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "price": {
                        "type": "number",
                        "description": "Total tax amount.",
                        "example": 0.31
                      },
                      "rate": {
                        "type": "number",
                        "description": "Tax rate as a decimal.",
                        "example": 0.08875
                      },
                      "title": {
                        "type": "string",
                        "description": "Name of the tax.",
                        "example": "SALES_TAX"
                      },
                      "inclusive": {
                        "type": "boolean",
                        "description": "Whether the tax is already in the price.",
                        "example": false
                      }
                    },
                    "required": [
                      "price",
                      "rate",
                      "title",
                      "inclusive"
                    ]
                  }
                }
              },
              "required": [
                "code",
                "title",
                "price",
                "total",
                "tax_lines"
              ]
            }
          },
          "subtotal_price": {
            "type": "number",
            "description": "Line item total before tax and shipping.",
            "example": 39.99
          },
          "tax_lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "price": {
                  "type": "number",
                  "description": "Total tax amount.",
                  "example": 2.12
                },
                "rate": {
                  "type": "number",
                  "description": "Tax rate as a decimal.",
                  "example": 0.08875
                },
                "title": {
                  "type": "string",
                  "description": "Name of the tax.",
                  "example": "SALES_TAX"
                }
              },
              "required": [
                "price",
                "rate",
                "title"
              ]
            }
          },
          "tax_included": {
            "type": "boolean",
            "description": "Whether listed prices already include tax.",
            "example": false
          },
          "total_discounts": {
            "type": "number",
            "example": 20.91
          },
          "total_price": {
            "type": "number",
            "example": 21.2
          },
          "total_tax": {
            "type": "number",
            "example": 2.12
          },
          "total_refunded": {
            "type": "number",
            "description": "Sum of all refunds issued.",
            "example": 5.5
          },
          "discount_applications": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "WELCOME40"
                },
                "allocation_method": {
                  "type": "string",
                  "example": "across"
                },
                "target_type": {
                  "type": "string",
                  "example": "line_item"
                },
                "type": {
                  "type": "string",
                  "example": "discount_code"
                },
                "value": {
                  "type": "number",
                  "example": 40
                },
                "value_type": {
                  "type": "string",
                  "example": "percentage"
                }
              },
              "required": [
                "code",
                "allocation_method",
                "target_type",
                "type",
                "value",
                "value_type"
              ]
            }
          },
          "discount_codes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "amount": {
                  "type": "number",
                  "example": 16.1
                },
                "code": {
                  "type": "string",
                  "example": "WELCOME40"
                },
                "type": {
                  "type": "string",
                  "example": "percentage"
                }
              },
              "required": [
                "amount",
                "code",
                "type"
              ]
            }
          },
          "exported_orders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "SHOPIFY_ORDER",
                    "SFCC_ORDER",
                    "PURPLE_DOT_FULFILLMENT_ORDER"
                  ],
                  "example": "SHOPIFY_ORDER"
                },
                "id": {
                  "type": "string",
                  "description": "The ID of the order in your platform, or the Purple Dot fulfillment order ID.",
                  "example": "5616927408181"
                },
                "order_number": {
                  "type": "string",
                  "example": "#3114029"
                },
                "created_at": {
                  "type": "string",
                  "example": "2024-11-14T16:22:59.432Z"
                },
                "line_items": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The platform line item ID.",
                        "example": "13278614585397"
                      },
                      "line_item_id": {
                        "type": "string",
                        "description": "The Purple Dot line item ID.",
                        "example": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
                      },
                      "quantity": {
                        "type": "number",
                        "example": 1
                      }
                    },
                    "required": [
                      "id",
                      "line_item_id"
                    ]
                  }
                }
              },
              "required": [
                "type",
                "id",
                "order_number",
                "created_at",
                "line_items"
              ]
            },
            "description": "Orders created in your platform from this pre-order."
          },
          "sales_channel": {
            "type": "string",
            "enum": [
              "online",
              "pos"
            ],
            "example": "online"
          },
          "pos_sale": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "cashier_staff_name": {
                "type": "string"
              },
              "staff_name": {
                "type": "string"
              },
              "location_name": {
                "type": "string"
              }
            },
            "required": [
              "cashier_staff_name",
              "staff_name",
              "location_name"
            ],
            "description": "Set if placed through Purple Dot POS."
          }
        },
        "required": [
          "id",
          "order_number",
          "reference",
          "cancel_reason",
          "cancelled_at",
          "created_at",
          "placed_at",
          "updated_at",
          "currency",
          "email",
          "customer",
          "line_items",
          "shipping_address",
          "shipping_lines",
          "subtotal_price",
          "tax_lines",
          "tax_included",
          "total_discounts",
          "total_price",
          "total_tax",
          "total_refunded",
          "discount_applications",
          "discount_codes",
          "exported_orders",
          "sales_channel",
          "pos_sale"
        ]
      },
      "FulfillmentOrder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Purple Dot ID.",
            "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
          },
          "status": {
            "type": "string",
            "description": "`UNFULFILLED` (waiting to be fulfilled), `FULFILLED` (all items fulfilled) or `VOIDED` (canceled).",
            "example": "UNFULFILLED"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When Purple Dot was told the line items are ready to fulfill.",
            "example": "2024-11-14T16:22:59.432Z"
          },
          "purchased_at": {
            "type": "string",
            "format": "date-time",
            "description": "`created_at` of the originating pre-order.",
            "example": "2024-11-14T16:18:25.635Z"
          },
          "reference": {
            "type": "string",
            "description": "The pre-order reference followed by the fulfillment order index.",
            "example": "#PD2850312/1"
          },
          "platform": {
            "type": "string",
            "enum": [
              "SHOPIFY",
              "HEADLESS"
            ],
            "example": "SHOPIFY"
          },
          "external_order_id": {
            "type": "string",
            "description": "The order's ID in your e-commerce platform.",
            "example": "gid://shopify/Order/5616927408181"
          },
          "shopify_order_id": {
            "type": "integer",
            "example": 5616927408181
          },
          "shopify_fulfillment_order_id": {
            "type": "integer",
            "example": 6988102148149
          },
          "currency": {
            "type": "string",
            "description": "Presentment currency.",
            "example": "USD"
          },
          "customer": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "example": "test@getpurpledot.com"
              },
              "first_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Test"
              },
              "last_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Testington"
              },
              "external_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "The Shopify customer ID, if known.",
                "example": 7287702192181
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string",
                  "example": "vip"
                },
                "description": "Shopify customer tags."
              },
              "default_address": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "first_name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Test"
                  },
                  "last_name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Testington"
                  },
                  "address1": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "10 Test Road"
                  },
                  "address2": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Apt 4B"
                  },
                  "city": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "New York"
                  },
                  "postal_code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "10463"
                  },
                  "province_code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ISO 3166 code for the second-level subdivision.",
                    "example": "NY"
                  },
                  "country": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "English country name.",
                    "example": "United States"
                  },
                  "country_code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ISO 3166 country code.",
                    "example": "US"
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "+19172756975"
                  }
                },
                "required": [
                  "first_name",
                  "last_name",
                  "address1",
                  "address2",
                  "city",
                  "postal_code",
                  "province_code",
                  "country",
                  "country_code",
                  "phone"
                ]
              }
            },
            "required": [
              "email",
              "first_name",
              "last_name",
              "external_id",
              "tags",
              "default_address"
            ]
          },
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Purple Dot ID.",
                  "example": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
                },
                "name": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The variant name.",
                  "example": "Test Product 1"
                },
                "product_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "6914583167029"
                },
                "variant_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "41125120573493"
                },
                "sku": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "PS4-GRVN"
                },
                "quantity": {
                  "type": "integer",
                  "example": 1
                },
                "price": {
                  "type": "number",
                  "description": "Unit price before taxes and discounts.",
                  "example": 39.99
                },
                "total": {
                  "type": "number",
                  "description": "Line item cost after taxes and discounts.",
                  "example": 26.01
                },
                "total_discount": {
                  "type": "number",
                  "example": 16.1
                },
                "discount_allocations": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "example": 16.1
                      },
                      "discount_application_index": {
                        "type": "integer",
                        "example": 0
                      }
                    },
                    "required": [
                      "amount",
                      "discount_application_index"
                    ]
                  }
                },
                "taxable": {
                  "type": "boolean",
                  "example": true
                },
                "tax_lines": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "price": {
                        "type": "number",
                        "example": 2.12
                      },
                      "rate": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "example": 0.08875
                      },
                      "title": {
                        "type": "string",
                        "example": "SALES_TAX"
                      },
                      "inclusive": {
                        "type": "boolean",
                        "example": false
                      }
                    },
                    "required": [
                      "price",
                      "rate",
                      "title",
                      "inclusive"
                    ]
                  }
                },
                "product_url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "https://example.com/products/test-product-1"
                },
                "image_url": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "https://example.com/images/test-product-1.jpg"
                },
                "shopify_fulfillment_order_line_item_id": {
                  "type": "integer",
                  "example": 14217093455925
                },
                "shopify_line_item_id": {
                  "type": "integer",
                  "example": 13278614585397
                }
              },
              "required": [
                "id",
                "name",
                "product_id",
                "variant_id",
                "sku",
                "quantity",
                "price",
                "total",
                "total_discount",
                "discount_allocations",
                "taxable",
                "tax_lines",
                "product_url",
                "image_url",
                "shopify_fulfillment_order_line_item_id",
                "shopify_line_item_id"
              ]
            }
          },
          "shipping_address": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "first_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Test"
              },
              "last_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Testington"
              },
              "address1": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "10 Test Road"
              },
              "address2": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Apt 4B"
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "New York"
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "10463"
              },
              "province_code": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 3166 code for the second-level subdivision.",
                "example": "NY"
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "English country name.",
                "example": "United States"
              },
              "country_code": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 3166 country code.",
                "example": "US"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "+19172756975"
              }
            },
            "required": [
              "first_name",
              "last_name",
              "address1",
              "address2",
              "city",
              "postal_code",
              "province_code",
              "country",
              "country_code",
              "phone"
            ]
          },
          "shipping_lines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Carrier code.",
                  "example": "usps_1058"
                },
                "title": {
                  "type": "string",
                  "description": "User-facing rate name.",
                  "example": "Calculated Shipping Rate"
                },
                "price": {
                  "type": "number",
                  "description": "Unit cost before taxes and discounts.",
                  "example": 5.98
                },
                "total": {
                  "type": "number",
                  "description": "Cost after taxes and discounts.",
                  "example": 3.88
                },
                "tax_lines": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "price": {
                        "type": "number",
                        "example": 0.31
                      },
                      "rate": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "example": 0.08875
                      },
                      "title": {
                        "type": "string",
                        "example": "SALES_TAX"
                      }
                    },
                    "required": [
                      "price",
                      "rate",
                      "title"
                    ]
                  }
                }
              },
              "required": [
                "code",
                "title",
                "price",
                "total",
                "tax_lines"
              ]
            }
          },
          "tax_included": {
            "type": "boolean",
            "description": "Whether tax is included in listed prices.",
            "example": false
          },
          "total_shipping": {
            "type": "number",
            "example": 3.88
          },
          "total_tax": {
            "type": "number",
            "example": 2.43
          },
          "total_discounts": {
            "type": "number",
            "example": 16.1
          },
          "subtotal_price": {
            "type": "number",
            "description": "Line item total before taxes and shipping.",
            "example": 39.99
          },
          "total_price": {
            "type": "number",
            "example": 29.89
          },
          "note": {
            "type": "string",
            "description": "Optional notes from the Shopify order.",
            "example": "Please leave at the front desk."
          }
        },
        "required": [
          "id",
          "status",
          "created_at",
          "purchased_at",
          "reference",
          "platform",
          "external_order_id",
          "shopify_order_id",
          "shopify_fulfillment_order_id",
          "currency",
          "customer",
          "line_items",
          "shipping_address",
          "shipping_lines",
          "tax_included",
          "total_shipping",
          "total_tax",
          "total_discounts",
          "subtotal_price",
          "total_price"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/inventory": {
      "post": {
        "tags": [
          "/inventory"
        ],
        "summary": "Set available inventory for a SKU",
        "description": "Sets the total number of available units Purple Dot uses when exporting pre-orders. Each call sets an absolute count, not a change, so repeating a request produces the same result.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sku": {
                    "anyOf": [
                      {
                        "type": "string",
                        "example": "LRS221"
                      },
                      {
                        "type": "number",
                        "example": "LRS221"
                      }
                    ],
                    "description": "The SKU whose inventory level is being updated.",
                    "example": "LRS221"
                  },
                  "available_units": {
                    "anyOf": [
                      {
                        "type": "number",
                        "example": 25
                      },
                      {
                        "type": "string",
                        "example": "25abc"
                      },
                      {
                        "type": "array",
                        "items": {},
                        "example": [
                          25
                        ]
                      }
                    ],
                    "description": "Available units, parsed as a base-10 integer using the legacy parseInt behavior. Decimal values are truncated and strings may have trailing text.",
                    "example": 25
                  },
                  "updated_at": {
                    "type": "string",
                    "description": "When the level was measured, as an ISO 8601 date or timestamp. Defaults to now.",
                    "example": "2024-11-14T16:22:59.432Z"
                  }
                },
                "required": [
                  "sku",
                  "available_units"
                ]
              },
              "example": {
                "sku": "LRS221",
                "available_units": 25,
                "updated_at": "2024-11-14T16:22:59.432Z"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The update was received.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "sku": {
                          "type": "string",
                          "example": "LRS221"
                        },
                        "available_units": {
                          "type": "integer",
                          "example": 25
                        }
                      },
                      "required": [
                        "sku",
                        "available_units"
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "sku": "LRS221",
                    "available_units": 25
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. A required attribute is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Missing attribute: sku"
                        }
                      },
                      "required": [
                        "error"
                      ]
                    }
                  ]
                },
                "example": {
                  "error": "Missing attribute: sku"
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/waitlists": {
      "get": {
        "tags": [
          "/waitlists"
        ],
        "summary": "List Waitlists",
        "description": "Lists Waitlists for the store, with cursor pagination. Per-product Waitlists return `null` for variant-level allocation fields.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "default": 10,
              "description": "Number of Waitlists to return. Defaults to 10, maximum 100.",
              "example": 10
            },
            "required": false,
            "description": "Number of Waitlists to return. Defaults to 10, maximum 100.",
            "name": "limit",
            "in": "query",
            "example": 10
          },
          {
            "schema": {
              "type": "string",
              "description": "Waitlists created at or after this time.",
              "example": "2025-01-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Waitlists created at or after this time.",
            "name": "created_at_min",
            "in": "query",
            "example": "2025-01-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Waitlists updated at or after this time.",
              "example": "2025-01-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Waitlists updated at or after this time.",
            "name": "updated_at_min",
            "in": "query",
            "example": "2025-01-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Waitlists updated at or before this time.",
              "example": "2025-12-31T23:59:59.000Z"
            },
            "required": false,
            "description": "Waitlists updated at or before this time.",
            "name": "updated_at_max",
            "in": "query",
            "example": "2025-12-31T23:59:59.000Z"
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Returns Waitlists after the given Waitlist ID.",
              "example": "a2aecc56-ce64-49da-8ce6-099e664d85fd"
            },
            "required": false,
            "description": "Returns Waitlists after the given Waitlist ID.",
            "name": "starting_after",
            "in": "query",
            "example": "a2aecc56-ce64-49da-8ce6-099e664d85fd"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated states to filter by, ignoring case: `LIVE`, `SCHEDULED`, `PAUSED` or `CLOSED`. Omit it for every Waitlist except drafts, which are never returned.",
              "example": "LIVE,SCHEDULED"
            },
            "required": false,
            "description": "Comma-separated states to filter by, ignoring case: `LIVE`, `SCHEDULED`, `PAUSED` or `CLOSED`. Omit it for every Waitlist except drafts, which are never returned.",
            "name": "state",
            "in": "query",
            "example": "LIVE,SCHEDULED"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of Waitlists.",
            "headers": {
              "Link": {
                "description": "Links to the previous and next pages of results. For compatibility, relations use the legacy `rel={next}` and `rel={previous}` syntax.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "waitlists": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Waitlist"
                          }
                        },
                        "has_more": {
                          "type": "boolean",
                          "description": "Whether more results are available after this page.",
                          "example": true
                        },
                        "starting_after": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "description": "ID of the last item returned. Pass it as `starting_after`.",
                          "example": "a2aecc56-ce64-49da-8ce6-099e664d85fd"
                        },
                        "previous_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "example": "0c34fc59-8a99-427f-a340-857e1eb9b6d2"
                        }
                      },
                      "required": [
                        "waitlists",
                        "has_more",
                        "starting_after",
                        "previous_cursor"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "waitlists": [
                      {
                        "id": "a2aecc56-ce64-49da-8ce6-099e664d85fd",
                        "created_at": "2023-10-27T14:44:09.726Z",
                        "updated_at": "2023-11-02T09:12:41.203Z",
                        "earliest_ship_date": "2023-11-25T05:00:00.000Z",
                        "latest_ship_date": "2023-12-10T04:59:59.999Z",
                        "state": "Live",
                        "launch_date": "2023-10-27T00:00:00.000Z",
                        "scheduled_pause_date": "2023-11-20T00:00:00.000Z",
                        "labels": [
                          "holiday"
                        ],
                        "availability": {
                          "product": {
                            "product_id": "7257265143861",
                            "buy_size": 10,
                            "committed": 3,
                            "available": 7
                          },
                          "variants": [
                            {
                              "variant_id": "42662551519285",
                              "sku": "ZTEST",
                              "buy_size": 10,
                              "committed": 3,
                              "available": 7
                            }
                          ]
                        }
                      }
                    ],
                    "has_more": true,
                    "starting_after": "a2aecc56-ce64-49da-8ce6-099e664d85fd",
                    "previous_cursor": "0c34fc59-8a99-427f-a340-857e1eb9b6d2"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid request, such as an unsupported `state` value.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "/waitlists"
        ],
        "summary": "Create a Waitlist",
        "description": "Creates a Waitlist for a product and ship date range. Also served at `/waitlist`.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WaitlistRequest"
              },
              "example": {
                "product_id": "7257265143861",
                "earliest_ship_date": "2025-03-01",
                "latest_ship_date": "2025-03-15",
                "max_units": [
                  {
                    "sku_id": "42662551519285",
                    "max_units": 50
                  },
                  {
                    "sku_id": "42662551552053",
                    "max_units": 30
                  }
                ],
                "state": "OPEN",
                "labels": [
                  "spring-2025"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Waitlist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/WaitlistSummary"
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "product_id": "7257265143861",
                    "state": "OPEN",
                    "earliest_ship_date": "2025-03-01T00:00:00Z",
                    "latest_ship_date": "2025-03-15T00:00:00Z",
                    "max_units": [
                      {
                        "sku_id": "42662551519285",
                        "max_units": 50
                      },
                      {
                        "sku_id": "42662551552053",
                        "max_units": 30
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid or missing fields.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The product or a variant was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "A Waitlist already exists for that product and ship date range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "/waitlists"
        ],
        "summary": "Create or update a Waitlist",
        "description": "Upserts a Waitlist. Updates the Waitlist with the same product and ship date range, or creates one if none exists. Also served at `/waitlist`.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WaitlistRequest"
              },
              "example": {
                "product_id": "7257265143861",
                "earliest_ship_date": "2025-03-01",
                "latest_ship_date": "2025-03-15",
                "max_units": [
                  {
                    "sku_id": "42662551519285",
                    "max_units": 50
                  },
                  {
                    "sku_id": "42662551552053",
                    "max_units": 30
                  }
                ],
                "state": "OPEN",
                "labels": [
                  "spring-2025"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Waitlist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/WaitlistSummary"
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "product_id": "7257265143861",
                    "state": "OPEN",
                    "earliest_ship_date": "2025-03-01T00:00:00Z",
                    "latest_ship_date": "2025-03-15T00:00:00Z",
                    "max_units": [
                      {
                        "sku_id": "42662551519285",
                        "max_units": 50
                      },
                      {
                        "sku_id": "42662551552053",
                        "max_units": 30
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid or missing fields.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The product or a variant was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/waitlists/{releaseId}": {
      "put": {
        "tags": [
          "/waitlists"
        ],
        "summary": "Update a Waitlist",
        "description": "Updates a specific Waitlist. `product_id` must match the Waitlist’s existing product. Also served at `/waitlist/{releaseId}`.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "The Waitlist ID.",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            },
            "required": true,
            "description": "The Waitlist ID.",
            "name": "releaseId",
            "in": "path",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WaitlistRequest"
              },
              "example": {
                "product_id": "7257265143861",
                "earliest_ship_date": "2025-03-01",
                "latest_ship_date": "2025-03-20",
                "max_units": [
                  {
                    "sku_id": "42662551519285",
                    "max_units": 75
                  }
                ],
                "state": "PAUSED",
                "labels": [
                  "spring-2025",
                  "delayed"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Waitlist.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/WaitlistSummary"
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "product_id": "7257265143861",
                    "state": "OPEN",
                    "earliest_ship_date": "2025-03-01T00:00:00Z",
                    "latest_ship_date": "2025-03-15T00:00:00Z",
                    "max_units": [
                      {
                        "sku_id": "42662551519285",
                        "max_units": 50
                      },
                      {
                        "sku_id": "42662551552053",
                        "max_units": 30
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid or missing fields.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The Waitlist was not found, or belongs to another store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/planned_inventory": {
      "post": {
        "tags": [
          "/planned_inventory"
        ],
        "summary": "Sync planned inventory",
        "description": "Reports inbound stock by SKU so Purple Dot creates and updates Waitlists to match. Returns the affected Waitlists.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "sku": {
                                  "type": "string",
                                  "minLength": 1,
                                  "example": "ZTEST"
                                }
                              },
                              "required": [
                                "sku"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "barcode": {
                                  "type": "string",
                                  "minLength": 1,
                                  "example": "0012345678905"
                                }
                              },
                              "required": [
                                "barcode"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "shopifyVariantGid": {
                                  "type": "string",
                                  "minLength": 1,
                                  "example": "gid://shopify/ProductVariant/42662551519285"
                                }
                              },
                              "required": [
                                "shopifyVariantGid"
                              ]
                            }
                          ]
                        },
                        "source_uri": {
                          "type": "string",
                          "minLength": 1,
                          "example": "po://PO-10234"
                        },
                        "labels": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "example": "purchase-order"
                          }
                        },
                        "quantity_expected": {
                          "type": "integer",
                          "minimum": 0,
                          "example": 120
                        },
                        "quantity_arrived": {
                          "type": "integer",
                          "minimum": 0,
                          "example": 0
                        },
                        "date_expected": {
                          "type": "string",
                          "example": "2025-03-10"
                        },
                        "inventory_location": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "name"
                                  ],
                                  "example": "name"
                                },
                                "name": {
                                  "type": "string",
                                  "minLength": 1,
                                  "example": "Main Warehouse"
                                }
                              },
                              "required": [
                                "type",
                                "name"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "shopifyInventoryLocationGid"
                                  ],
                                  "example": "name"
                                },
                                "shopifyInventoryLocationGid": {
                                  "type": "string",
                                  "minLength": 1,
                                  "example": "gid://shopify/Location/68031475893"
                                }
                              },
                              "required": [
                                "type",
                                "shopifyInventoryLocationGid"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "source_uri",
                        "labels",
                        "quantity_expected",
                        "quantity_arrived",
                        "date_expected",
                        "inventory_location"
                      ]
                    },
                    "minItems": 1
                  }
                },
                "required": [
                  "items"
                ]
              },
              "example": {
                "items": [
                  {
                    "id": {
                      "sku": "ZTEST"
                    },
                    "source_uri": "po://PO-10234",
                    "labels": [
                      "purchase-order"
                    ],
                    "quantity_expected": 120,
                    "quantity_arrived": 0,
                    "date_expected": "2025-03-10",
                    "inventory_location": {
                      "type": "name",
                      "name": "Main Warehouse"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The affected Waitlists.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "waitlists": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Waitlist"
                          }
                        }
                      },
                      "required": [
                        "waitlists"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "waitlists": [
                      {
                        "id": "a2aecc56-ce64-49da-8ce6-099e664d85fd",
                        "created_at": "2023-10-27T14:44:09.726Z",
                        "updated_at": "2023-11-02T09:12:41.203Z",
                        "earliest_ship_date": "2023-11-25T05:00:00.000Z",
                        "latest_ship_date": "2023-12-10T04:59:59.999Z",
                        "state": "Live",
                        "launch_date": "2023-10-27T00:00:00.000Z",
                        "scheduled_pause_date": "2023-11-20T00:00:00.000Z",
                        "labels": [
                          "holiday"
                        ],
                        "availability": {
                          "product": {
                            "product_id": "7257265143861",
                            "buy_size": 10,
                            "committed": 3,
                            "available": 7
                          },
                          "variants": [
                            {
                              "variant_id": "42662551519285",
                              "sku": "ZTEST",
                              "buy_size": 10,
                              "committed": 3,
                              "available": 7
                            }
                          ]
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid or missing fields.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "An item could not be matched to a product.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/pre-orders": {
      "get": {
        "tags": [
          "/pre-orders"
        ],
        "summary": "List pre-orders",
        "description": "Lists pre-orders. With the platform integration and combined cart, in-stock purchases made through Purple Dot’s checkout are not included.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "default": 10,
              "description": "Number of pre-orders to return. Defaults to 10, maximum 200.",
              "example": 25
            },
            "required": false,
            "description": "Number of pre-orders to return. Defaults to 10, maximum 200.",
            "name": "limit",
            "in": "query",
            "example": 25
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Returns pre-orders after the given pre-order ID.",
              "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
            },
            "required": false,
            "description": "Returns pre-orders after the given pre-order ID.",
            "name": "starting_after",
            "in": "query",
            "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated, URL-encoded Purple Dot order references.",
              "example": "#PD2850312,#PD2850313"
            },
            "required": false,
            "description": "Comma-separated, URL-encoded Purple Dot order references.",
            "name": "references",
            "in": "query",
            "example": "#PD2850312,#PD2850313"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders created at or after this time.",
              "example": "2024-11-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders created at or after this time.",
            "name": "created_at_min",
            "in": "query",
            "example": "2024-11-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders updated at or after this time.",
              "example": "2024-11-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders updated at or after this time.",
            "name": "updated_at_min",
            "in": "query",
            "example": "2024-11-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders updated at or before this time.",
              "example": "2024-12-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders updated at or before this time.",
            "name": "updated_at_max",
            "in": "query",
            "example": "2024-12-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Matches pre-orders where every line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`.",
              "example": "exported"
            },
            "required": false,
            "description": "Matches pre-orders where every line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`.",
            "name": "all_line_items",
            "in": "query",
            "example": "exported"
          },
          {
            "schema": {
              "type": "string",
              "description": "Matches pre-orders where at least one line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`. Cannot be combined with `all_line_items`."
            },
            "required": false,
            "description": "Matches pre-orders where at least one line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`. Cannot be combined with `all_line_items`.",
            "name": "some_line_item",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated product variant SKUs.",
              "example": "PS4-GRVN,P5LR123"
            },
            "required": false,
            "description": "Comma-separated product variant SKUs.",
            "name": "skus",
            "in": "query",
            "example": "PS4-GRVN,P5LR123"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders placed by this email address.",
              "example": "test@getpurpledot.com"
            },
            "required": false,
            "description": "Pre-orders placed by this email address.",
            "name": "email",
            "in": "query",
            "example": "test@getpurpledot.com"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of pre-orders.",
            "headers": {
              "Link": {
                "description": "Links to the previous and next pages of results. For compatibility, relations use the legacy `rel={next}` and `rel={previous}` syntax.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "orders": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Pre-order"
                          }
                        },
                        "has_more": {
                          "type": "boolean",
                          "description": "Whether more results are available after this page.",
                          "example": false
                        },
                        "starting_after": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "description": "ID of the last item returned. Pass it as `starting_after`.",
                          "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
                        },
                        "previous_cursor": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "example": "935bad68-2726-4ad1-b299-a330650a2bbb"
                        }
                      },
                      "required": [
                        "orders",
                        "has_more",
                        "starting_after",
                        "previous_cursor"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "orders": [
                      {
                        "id": "58da51c9-9b48-48c6-beb5-46bd34834960",
                        "order_number": "2850312",
                        "reference": "#PD2850312",
                        "cancel_reason": "customer",
                        "cancelled_at": "2024-11-14T16:20:39.796Z",
                        "created_at": "2024-11-14T16:18:25.635Z",
                        "placed_at": "2024-11-14T16:18:25.635Z",
                        "updated_at": "2024-11-14T16:23:02.118Z",
                        "currency": "USD",
                        "email": "test@getpurpledot.com",
                        "customer": {
                          "email": "test@getpurpledot.com",
                          "external_id": "7287702192181"
                        },
                        "line_items": [
                          {
                            "id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
                            "name": "Test Product 1",
                            "sku": "PS4-GRVN",
                            "product_id": "6914583167029",
                            "variant_id": "41125120573493",
                            "waitlist_id": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec",
                            "quantity": 1,
                            "price": 39.99,
                            "total": 26.01,
                            "total_discount": 16.1,
                            "discount_allocations": [
                              {
                                "amount": 16.1,
                                "discount_application_index": 0
                              }
                            ],
                            "taxable": true,
                            "tax_lines": [
                              {
                                "price": 2.12,
                                "rate": 0.08875,
                                "title": "SALES_TAX",
                                "inclusive": false
                              }
                            ]
                          }
                        ],
                        "shipping_address": {
                          "first_name": "Test",
                          "last_name": "Testington",
                          "address1": "10 Test Road",
                          "address2": "Apt 4B",
                          "city": "New York",
                          "postal_code": "10463",
                          "province_code": "NY",
                          "country": "United States",
                          "country_code": "US",
                          "phone": "+19172756975"
                        },
                        "shipping_lines": [
                          {
                            "code": "usps_1058",
                            "title": "Calculated Shipping Rate",
                            "price": 5.98,
                            "total": 3.88,
                            "tax_lines": [
                              {
                                "price": 0.31,
                                "rate": 0.08875,
                                "title": "SALES_TAX",
                                "inclusive": false
                              }
                            ]
                          }
                        ],
                        "subtotal_price": 39.99,
                        "tax_lines": [
                          {
                            "price": 2.12,
                            "rate": 0.08875,
                            "title": "SALES_TAX"
                          }
                        ],
                        "tax_included": false,
                        "total_discounts": 20.91,
                        "total_price": 21.2,
                        "total_tax": 2.12,
                        "total_refunded": 5.5,
                        "discount_applications": [
                          {
                            "code": "WELCOME40",
                            "allocation_method": "across",
                            "target_type": "line_item",
                            "type": "discount_code",
                            "value": 40,
                            "value_type": "percentage"
                          }
                        ],
                        "discount_codes": [
                          {
                            "amount": 16.1,
                            "code": "WELCOME40",
                            "type": "percentage"
                          }
                        ],
                        "exported_orders": [
                          {
                            "type": "SHOPIFY_ORDER",
                            "id": "5616927408181",
                            "order_number": "#3114029",
                            "created_at": "2024-11-14T16:22:59.432Z",
                            "line_items": [
                              {
                                "id": "13278614585397",
                                "line_item_id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
                                "quantity": 1
                              }
                            ]
                          }
                        ],
                        "sales_channel": "online",
                        "pos_sale": null
                      }
                    ],
                    "has_more": false,
                    "starting_after": "58da51c9-9b48-48c6-beb5-46bd34834960",
                    "previous_cursor": "935bad68-2726-4ad1-b299-a330650a2bbb"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. The limit is above 200, or both `all_line_items` and `some_line_item` were passed.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/pre-orders/count": {
      "get": {
        "tags": [
          "/pre-orders/count"
        ],
        "summary": "Count pre-orders",
        "description": "Counts all pre-orders that match the given criteria.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders created at or after this time.",
              "example": "2024-11-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders created at or after this time.",
            "name": "created_at_min",
            "in": "query",
            "example": "2024-11-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders updated at or after this time.",
              "example": "2024-11-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders updated at or after this time.",
            "name": "updated_at_min",
            "in": "query",
            "example": "2024-11-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders updated at or before this time.",
              "example": "2024-12-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders updated at or before this time.",
            "name": "updated_at_max",
            "in": "query",
            "example": "2024-12-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Matches pre-orders where every line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`.",
              "example": "exported"
            },
            "required": false,
            "description": "Matches pre-orders where every line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`.",
            "name": "all_line_items",
            "in": "query",
            "example": "exported"
          },
          {
            "schema": {
              "type": "string",
              "description": "Matches pre-orders where at least one line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`. Cannot be combined with `all_line_items`."
            },
            "required": false,
            "description": "Matches pre-orders where at least one line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`. Cannot be combined with `all_line_items`.",
            "name": "some_line_item",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated product variant SKUs.",
              "example": "PS4-GRVN,P5LR123"
            },
            "required": false,
            "description": "Comma-separated product variant SKUs.",
            "name": "skus",
            "in": "query",
            "example": "PS4-GRVN,P5LR123"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders placed by this email address.",
              "example": "test@getpurpledot.com"
            },
            "required": false,
            "description": "Pre-orders placed by this email address.",
            "name": "email",
            "in": "query",
            "example": "test@getpurpledot.com"
          }
        ],
        "responses": {
          "200": {
            "description": "The number of matching pre-orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "example": 42
                        }
                      },
                      "required": [
                        "count"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "count": 42
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Both `all_line_items` and `some_line_item` were passed.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/pre-orders/count-units/sku/{sku}": {
      "get": {
        "tags": [
          "/pre-orders/count-units/sku/:sku"
        ],
        "summary": "Count pre-order units for a SKU",
        "description": "Returns counts of open, canceled and exported pre-order units for a single SKU.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The SKU code to count.",
              "example": "LRS221"
            },
            "required": true,
            "description": "The SKU code to count.",
            "name": "sku",
            "in": "path",
            "example": "LRS221"
          },
          {
            "schema": {
              "type": "string",
              "description": "The counts reflect the state at this moment. Defaults to the current time. Cannot be in the future.",
              "example": "2023-08-18T09:57:49.576Z"
            },
            "required": false,
            "description": "The counts reflect the state at this moment. Defaults to the current time. Cannot be in the future.",
            "name": "at_time",
            "in": "query",
            "example": "2023-08-18T09:57:49.576Z"
          }
        ],
        "responses": {
          "200": {
            "description": "Unit counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "sku": {
                          "type": "string",
                          "example": "LRS221"
                        },
                        "at_time": {
                          "type": "string",
                          "format": "date-time",
                          "description": "The time the counts were calculated for.",
                          "example": "2023-08-18T09:57:49.576Z"
                        },
                        "open_units": {
                          "type": "integer",
                          "description": "Units purchased through Purple Dot and still held there because they are not ready for fulfilment. An open unit ends up either canceled or exported, never both.",
                          "example": 14
                        },
                        "canceled_units": {
                          "type": "integer",
                          "description": "Units later canceled by the shopper or the merchant.",
                          "example": 15
                        },
                        "exported_units": {
                          "type": "integer",
                          "description": "Units later exported to the external e-commerce platform.",
                          "example": 12
                        }
                      },
                      "required": [
                        "sku",
                        "at_time",
                        "open_units",
                        "canceled_units",
                        "exported_units"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "sku": "LRS221",
                    "at_time": "2023-08-18T09:57:49.576Z",
                    "open_units": 14,
                    "canceled_units": 15,
                    "exported_units": 12
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. `at_time` is in the future, or the store’s platform is unsupported.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/refund": {
      "post": {
        "tags": [
          "/refund"
        ],
        "summary": "Create a refund",
        "description": "Creates a refund for an order, paid back to the shopper against the underlying Purple Dot pre-order payments. Use either a line-item refund (`line_items` and/or `shipping`) or a custom amount refund (`amount` and `currency`), not both. Line-item refunds are supported only for Shopify stores.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Idempotency key, unique for each distinct refund (a refund document number, return ID or support ticket ID). To retry after a timeout, reuse the same `id`, `order` and payload: a prior success returns the same result and does not refund the shopper twice. The same `id` and `order` with a different payload returns `409`. Use a new `id` for each separate refund, even on the same order.",
                    "example": "refund-001"
                  },
                  "order": {
                    "type": "string",
                    "description": "External order ID to refund. On Shopify, the Shopify order ID. On other platforms, the Purple Dot fulfillment order UUID from `GET /fulfillment-orders`.",
                    "example": "gid://shopify/Order/5616927408181"
                  },
                  "line_items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "External line item ID (for example, the Shopify line item ID).",
                          "example": "gid://shopify/LineItem/13278614585397"
                        },
                        "quantity": {
                          "type": "number",
                          "enum": [
                            1
                          ],
                          "description": "Must be `1`.",
                          "example": 1
                        }
                      },
                      "required": [
                        "id",
                        "quantity"
                      ]
                    },
                    "description": "Line-item refunds only. The line items to refund."
                  },
                  "shipping": {
                    "type": "boolean",
                    "default": false,
                    "description": "Line-item refunds only. Refunds shipping for the order. Shipping can be refunded only once per order.",
                    "example": false
                  },
                  "amount": {
                    "type": "string",
                    "description": "Custom amount refunds only. Amount to refund, as a decimal string.",
                    "example": "10.00"
                  },
                  "currency": {
                    "type": "string",
                    "description": "Custom amount refunds only. Must match the order's presentment currency.",
                    "example": "USD"
                  }
                },
                "required": [
                  "id",
                  "order"
                ]
              },
              "example": {
                "id": "refund-001",
                "order": "gid://shopify/Order/5616927408181",
                "line_items": [
                  {
                    "id": "gid://shopify/LineItem/13278614585397",
                    "quantity": 1
                  }
                ],
                "shipping": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The refund.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Idempotency key from the request.",
                          "example": "refund-001"
                        },
                        "order": {
                          "type": "string",
                          "description": "External order ID from the request.",
                          "example": "gid://shopify/Order/5616927408181"
                        },
                        "refunded": {
                          "type": "object",
                          "properties": {
                            "amount": {
                              "type": "string",
                              "example": "26.01"
                            },
                            "currency": {
                              "type": "string",
                              "example": "USD"
                            }
                          },
                          "required": [
                            "amount",
                            "currency"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "order",
                        "refunded"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "id": "refund-001",
                    "order": "gid://shopify/Order/5616927408181",
                    "refunded": {
                      "amount": "26.01",
                      "currency": "USD"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. One of `INVALID_REFUND_REQUEST`, `INVALID_LINE_ITEMS`, `CURRENCY_MISMATCH`, `SHIPPING_ALREADY_REFUNDED` or `NOT_ENOUGH_ITEMS_LEFT_TO_REFUND`.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "One of `UNKNOWN_ORDER` or `UNKNOWN_LINE_ITEMS`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "`IDEMPOTENT_REQUEST_PAYLOAD_MISMATCH`: the same `id` and `order` were used with a different payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "The refund could not be completed, including orders spanning multiple pre-orders, mixed checkout and pre-order line items, or payment refund failures. `meta.error` contains a generic error message; `meta.errorData` may contain request details, but no refund failure code is exposed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/fulfillment-orders": {
      "get": {
        "tags": [
          "/fulfillment-orders"
        ],
        "summary": "List fulfillment orders",
        "description": "Lists fulfillment orders across pre-orders that are now fulfillable. Results are paginated.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "default": 50,
              "description": "Number of fulfillment orders to return, from 1 to 250. Defaults to 50.",
              "example": 50
            },
            "required": false,
            "description": "Number of fulfillment orders to return, from 1 to 250. Defaults to 50.",
            "name": "limit",
            "in": "query",
            "example": 50
          },
          {
            "schema": {
              "type": "string",
              "description": "Fulfillment orders created at or after this time.",
              "example": "2024-11-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Fulfillment orders created at or after this time.",
            "name": "created_at_min",
            "in": "query",
            "example": "2024-11-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Returns fulfillment orders after the given fulfillment order ID.",
              "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
            },
            "required": false,
            "description": "Returns fulfillment orders after the given fulfillment order ID.",
            "name": "starting_after",
            "in": "query",
            "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated, URL-encoded Purple Dot fulfillment order references.",
              "example": "#PD2850312/1"
            },
            "required": false,
            "description": "Comma-separated, URL-encoded Purple Dot fulfillment order references.",
            "name": "references",
            "in": "query",
            "example": "#PD2850312/1"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of fulfillment orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "fulfillment_orders": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/FulfillmentOrder"
                          }
                        },
                        "has_more": {
                          "type": "boolean",
                          "description": "Whether more results are available after this page.",
                          "example": false
                        },
                        "starting_after": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "description": "ID of the last item returned. Pass it as `starting_after`.",
                          "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
                        }
                      },
                      "required": [
                        "fulfillment_orders",
                        "has_more",
                        "starting_after"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "fulfillment_orders": [
                      {
                        "id": "a1b2c3d4-e5f6-4890-9234-567890abcdef",
                        "status": "UNFULFILLED",
                        "created_at": "2024-11-14T16:22:59.432Z",
                        "purchased_at": "2024-11-14T16:18:25.635Z",
                        "reference": "#PD2850312/1",
                        "platform": "SHOPIFY",
                        "external_order_id": "gid://shopify/Order/5616927408181",
                        "shopify_order_id": 5616927408181,
                        "shopify_fulfillment_order_id": 6988102148149,
                        "currency": "USD",
                        "customer": {
                          "email": "test@getpurpledot.com",
                          "first_name": "Test",
                          "last_name": "Testington",
                          "external_id": 7287702192181,
                          "tags": [
                            "vip"
                          ],
                          "default_address": {
                            "first_name": "Test",
                            "last_name": "Testington",
                            "address1": "10 Test Road",
                            "address2": "Apt 4B",
                            "city": "New York",
                            "postal_code": "10463",
                            "province_code": "NY",
                            "country": "United States",
                            "country_code": "US",
                            "phone": "+19172756975"
                          }
                        },
                        "line_items": [
                          {
                            "id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
                            "name": "Test Product 1",
                            "product_id": "6914583167029",
                            "variant_id": "41125120573493",
                            "sku": "PS4-GRVN",
                            "quantity": 1,
                            "price": 39.99,
                            "total": 26.01,
                            "total_discount": 16.1,
                            "discount_allocations": [
                              {
                                "amount": 16.1,
                                "discount_application_index": 0
                              }
                            ],
                            "taxable": true,
                            "tax_lines": [
                              {
                                "price": 2.12,
                                "rate": 0.08875,
                                "title": "SALES_TAX",
                                "inclusive": false
                              }
                            ],
                            "product_url": "https://example.com/products/test-product-1",
                            "image_url": "https://example.com/images/test-product-1.jpg",
                            "shopify_fulfillment_order_line_item_id": 14217093455925,
                            "shopify_line_item_id": 13278614585397
                          }
                        ],
                        "shipping_address": {
                          "first_name": "Test",
                          "last_name": "Testington",
                          "address1": "10 Test Road",
                          "address2": "Apt 4B",
                          "city": "New York",
                          "postal_code": "10463",
                          "province_code": "NY",
                          "country": "United States",
                          "country_code": "US",
                          "phone": "+19172756975"
                        },
                        "shipping_lines": [
                          {
                            "code": "usps_1058",
                            "title": "Calculated Shipping Rate",
                            "price": 5.98,
                            "total": 3.88,
                            "tax_lines": [
                              {
                                "price": 0.31,
                                "rate": 0.08875,
                                "title": "SALES_TAX"
                              }
                            ]
                          }
                        ],
                        "tax_included": false,
                        "total_shipping": 3.88,
                        "total_tax": 2.43,
                        "total_discounts": 16.1,
                        "subtotal_price": 39.99,
                        "total_price": 29.89,
                        "note": "Please leave at the front desk."
                      }
                    ],
                    "starting_after": "a1b2c3d4-e5f6-4890-9234-567890abcdef",
                    "has_more": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/fulfillment-orders/{fulfillmentOrderId}": {
      "get": {
        "tags": [
          "/fulfillment-orders/:id"
        ],
        "summary": "Get a fulfillment order",
        "security": [
          {
            "accessToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The Purple Dot ID of the fulfillment order.",
              "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
            },
            "required": true,
            "description": "The Purple Dot ID of the fulfillment order.",
            "name": "fulfillmentOrderId",
            "in": "path",
            "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
          }
        ],
        "responses": {
          "200": {
            "description": "The fulfillment order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/FulfillmentOrder"
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "id": "a1b2c3d4-e5f6-4890-9234-567890abcdef",
                    "status": "UNFULFILLED",
                    "created_at": "2024-11-14T16:22:59.432Z",
                    "purchased_at": "2024-11-14T16:18:25.635Z",
                    "reference": "#PD2850312/1",
                    "platform": "SHOPIFY",
                    "external_order_id": "gid://shopify/Order/5616927408181",
                    "shopify_order_id": 5616927408181,
                    "shopify_fulfillment_order_id": 6988102148149,
                    "currency": "USD",
                    "customer": {
                      "email": "test@getpurpledot.com",
                      "first_name": "Test",
                      "last_name": "Testington",
                      "external_id": 7287702192181,
                      "tags": [
                        "vip"
                      ],
                      "default_address": {
                        "first_name": "Test",
                        "last_name": "Testington",
                        "address1": "10 Test Road",
                        "address2": "Apt 4B",
                        "city": "New York",
                        "postal_code": "10463",
                        "province_code": "NY",
                        "country": "United States",
                        "country_code": "US",
                        "phone": "+19172756975"
                      }
                    },
                    "line_items": [
                      {
                        "id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
                        "name": "Test Product 1",
                        "product_id": "6914583167029",
                        "variant_id": "41125120573493",
                        "sku": "PS4-GRVN",
                        "quantity": 1,
                        "price": 39.99,
                        "total": 26.01,
                        "total_discount": 16.1,
                        "discount_allocations": [
                          {
                            "amount": 16.1,
                            "discount_application_index": 0
                          }
                        ],
                        "taxable": true,
                        "tax_lines": [
                          {
                            "price": 2.12,
                            "rate": 0.08875,
                            "title": "SALES_TAX",
                            "inclusive": false
                          }
                        ],
                        "product_url": "https://example.com/products/test-product-1",
                        "image_url": "https://example.com/images/test-product-1.jpg",
                        "shopify_fulfillment_order_line_item_id": 14217093455925,
                        "shopify_line_item_id": 13278614585397
                      }
                    ],
                    "shipping_address": {
                      "first_name": "Test",
                      "last_name": "Testington",
                      "address1": "10 Test Road",
                      "address2": "Apt 4B",
                      "city": "New York",
                      "postal_code": "10463",
                      "province_code": "NY",
                      "country": "United States",
                      "country_code": "US",
                      "phone": "+19172756975"
                    },
                    "shipping_lines": [
                      {
                        "code": "usps_1058",
                        "title": "Calculated Shipping Rate",
                        "price": 5.98,
                        "total": 3.88,
                        "tax_lines": [
                          {
                            "price": 0.31,
                            "rate": 0.08875,
                            "title": "SALES_TAX"
                          }
                        ]
                      }
                    ],
                    "tax_included": false,
                    "total_shipping": 3.88,
                    "total_tax": 2.43,
                    "total_discounts": 16.1,
                    "subtotal_price": 39.99,
                    "total_price": 29.89,
                    "note": "Please leave at the front desk."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The fulfillment order was not found in the authenticated store.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/fulfillment": {
      "post": {
        "tags": [
          "/fulfillment"
        ],
        "summary": "Create a fulfillment",
        "description": "Creates a fulfillment for a fulfillment order.",
        "security": [
          {
            "accessToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fulfillment": {
                    "type": "object",
                    "properties": {
                      "fulfillment_order_id": {
                        "type": "string",
                        "example": "a1b2c3d4-e5f6-4890-9234-567890abcdef"
                      },
                      "line_items": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "minLength": 1,
                              "example": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
                            },
                            "quantity": {
                              "type": "number",
                              "example": 1
                            }
                          },
                          "required": [
                            "id",
                            "quantity"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "notify_customer": {
                        "type": "boolean",
                        "example": true
                      },
                      "tracking_info": {
                        "type": "object",
                        "properties": {
                          "number": {
                            "type": "string",
                            "example": "1234567890"
                          },
                          "url": {
                            "type": "string",
                            "example": "https://www.myshipping.com/track/?tracknumbers=1234567890"
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "fulfillment_order_id"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "fulfillment"
                ],
                "additionalProperties": false
              },
              "example": {
                "fulfillment": {
                  "fulfillment_order_id": "a1b2c3d4-e5f6-4890-9234-567890abcdef",
                  "line_items": [
                    {
                      "id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
                      "quantity": 1
                    }
                  ],
                  "notify_customer": true,
                  "tracking_info": {
                    "number": "1234567890",
                    "url": "https://www.myshipping.com/track/?tracknumbers=1234567890"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The fulfillment was created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "enum": [
                            true
                          ],
                          "example": true
                        }
                      },
                      "required": [
                        "success"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing access token. Invalid body, or a line item is not in the fulfillment order.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Access token not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The fulfillment order was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}
