--- title: "PUT /orders/{order_id}/cancel" method: PUT path: "/orders/{order_id}/cancel" tags: ["Orders"] --- # PUT /orders/{order_id}/cancel `PUT /orders/{order_id}/cancel` This endpoint cancels an order and places it in the state CANCELED. The order can be canceled only if it has a state of NEW, PROCESSING, PENDING_RETAILER_CONFIRMATION or BACKORDERED. ## Path parameters - `order_id` string, required ## Request body - ExternalCancelBrandOrderRequestV2 — Request to cancel an order, including the reason and an optional note. - `note` string — A note explaining to the retailer why their order was canceled. The note must be between 30 and 1000 characters long. - `reason` 'REQUESTED_BY_RETAILER' | 'RETAILER_NOT_GOOD_FIT' | 'CHANGE_REPLACE_ORDER' | 'ITEM_OUT_OF_STOCK' | 'INCORRECT_PRICING' | 'ORDER_TOO_SMALL' | 'REJECT_INTERNATIONAL_ORDER' | 'OTHER' — Reasons why a brand may cancel an order. Used when calling the cancel order endpoint. ## Response `200` Successful response - ExternalOrderV2 — Internally maps to a brand order. - `id` string — Read-only. A unique identifier of the order, beginning with "bo_". NOTE: When shown on the Faire website, the "bo_" will be stripped and the order ID will be upper-case. e.g. "bo_bxdmjbwxid" appears as "#BXDMJBWXID" (See display_id). - `display_id` string — Read-only. The order identifier as displayed on the Faire website, emails, etc. - `created_at` string — Read-only. An ISO 8601 timestamp of when the order was created. - `updated_at` string — Read-only. An ISO 8601 timestamp of when the order was last updated. - `state` 'NEW' | 'PROCESSING' | 'PRE_TRANSIT' | 'IN_TRANSIT' | 'DELIVERED' | 'CANCELED' | 'BACKORDERED' | 'PENDING_RETAILER_CONFIRMATION' - `items` ExternalOrderItemV2[] — A list of order items associated with the order. - `id` string — Read-only. A unique identifier of the order item, beginning with "oi_". - `created_at` string — Read-only. An ISO 8601 timestamp of when the order item was created. - `updated_at` string — Read-only. An ISO 8601 timestamp of when the order item was last updated. - `order_id` string — The ID of the order the item belongs to. - `product_id` string — The ID of the product the retailer bought. - `variant_id` string — The ID of the variant the retailer bought. - `quantity` integer — The number of physical items the retailer purchased. - `sku` string — The SKU of the variant when the order was created. This may not match the current SKU of the variant. - `price_cents` integer — The wholesale price of the product at the time it was purchased, in USD cents. Deprecated - use price instead. - `product_name` string — The name of the product when it was purchased. - `variant_name` string — The name of the variant when it was purchased. - `includes_tester` boolean — A boolean indicating whether or not a tester for the variant was purchased. - `tester_price_cents` integer — If includes_tester is true, the price of the tester in USD cents. Deprecated - use testerPrice instead. - `customizations` ExternalOrderItemV2Customization[] — A list of customizations applied to this order item. - `token` string — The unique token identifying this customization. - `type` string — The type of customization. - `value` string — The value or content of the customization. - `price` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `tester_price` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `discounts` ExternalDiscountV2[] — A list of any product-specific promotions that were applied to this item. Does not include shop-wide promotions, which can be found under the order's brand_discounts field. - `id` string — A unique identifier for the discount, beginning with "bpc_". - `code` string — The name of the promotion as it appears to retailers at checkout. - `discount_type` 'FLAT_AMOUNT' | 'PERCENTAGE' | 'NONE' — The type of discount applied - either a flat amount off or a percentage off the order. - `discount_amount_cents` integer — Deprecated. Depending on discountType either discountAmountCents or discountPercentage is populated. - `discount_percentage` number — The discount amount as a percent of the total. This value is present only when the discount_type is PERCENTAGE. - `includes_free_shipping` boolean — Whether this promotion is for free shipping. - `discount_amount` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `state` 'CANCELED' | 'PROCESSING' | 'PRE_TRANSIT' | 'IN_TRANSIT' | 'DELIVERED' | 'RETURNED' | 'BACKORDERED' | 'DAMAGED_OR_MISSING' | 'PENDING_RETAILER_CONFIRMATION' - `shipments` ExternalShipmentV2[] — A list of shipments associated with the order. - `id` string — Read-only. A unique identifier of the shipment, beginning with "s_". - `created_at` string — Read-only. An ISO 8601 timestamp of when the shipment was created. - `updated_at` string — Read-only. An ISO 8601 timestamp of when the shipment was last updated. - `order_id` string — The ID of the order the shipment is attached to. - `maker_cost_cents` integer — The cost the brand paid to ship the order, in USD cents. Deprecated - use makerCost instead. - `carrier` string — The carrier the brand used to ship the order. Currently, the accepted values are CANADA_POST, DHL_ECOMMERCE, DHL_EXPRESS, FEDEX, PUROLATOR, UPS, USPS, POSTNL, CANPAR, INTERLINK_EXPRESS, GSO, ROYAL_MAIL, DPD, DPDUK, PARCELFORCE, AUSTRALIA_POST, EVRI, and LA_POSTE. These values are case insensitive. If another string is entered for this field, Faire will do its best to produce tracking information for that carrier, but may not succeed. - `tracking_code` string — The tracking code for the shipment, format varies based on the carrier. - `maker_cost` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `shipping_type` 'SHIP_ON_YOUR_OWN' | 'SHIP_WITH_FAIRE' — How the shipment is being handled - either the brand ships it themselves or uses Faire's shipping service. - `shipping_label_url` string — A URL to the shipping label for this shipment, if available. This field is read-only. - `commercial_invoice_url` string — Read-only. A URL to the commercial invoice for this shipment, if available. - `address` ExternalAddressV2 — Contains information about the location of a person or business. Typically used to describe where to ship an order. - `id` string — Read-only. The unique identifier of the address, beginning with "a_". - `name` string — The name of the individual (recipient) to contact at the address. - `address1` string — The first line of street address information. - `address2` string — Optional. The second line of street address information. - `postal_code` string — The ZIP/postal code. - `city` string — The city name. - `state` string — The full name of the state or province. - `state_code` string — The ISO 3166 two-letter code for the state or province. - `phone_number` string — The phone number used to contact the recipient. - `country` string — The full name of the country. - `country_code` string — The ISO alpha-3 country code. - `company_name` string — The name of the company at this address. - `address_type` 'RESIDENTIAL' | 'COMMERCIAL' | 'MIXED' — These are different address specifications. - `ship_after` string — An ISO 8601 timestamp of the earliest the order should ship. - `payout_costs` ExternalPayoutCostsV2 - `payout_fee_cents` integer — The amount charged to the brand to pay out the order, (e.g. for next-day ACH transfers), in USD cents. Deprecated - use payoutFee instead. - `payout_fee_bps` integer — The payout fee basis points used to calculate the payout fee (e.g. 300 is 3%). - `payout_flat_fee` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `commission_cents` integer — The amount of commission charged to the brand for the order, in USD cents. Deprecated - use commission instead. - `commission_bps` integer — The commission basis points used to calculate the commission (e.g. 1500 is 15%). - `commission_flat_fee` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `payout_fee` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `commission` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `total_payout` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `payout_protection_fee` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `damaged_and_missing_items` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `net_tax` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `shipping_subsidy` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `taxes` ExternalTaxItemV2[] — A list of the individual taxes that make up net_tax. - `value` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `taxable_item_type` 'ORDER_ITEM' | 'SHIPPING' | 'INSIDER_MEMBERSHIP' | 'ORDER_COMMISSION' | 'ADS_CHARGE' | 'ORDER_SHIP_WITH_FAIRE' - `tax_type` 'CANADIAN_TAX' | 'VAT' | 'VAT_REVERSE_CHARGE' | 'INTRA_COMMUNITY_SUPPLY' | 'GST' | 'HST' | 'PST' | 'ESTIMATED_IMPORT_VAT' | 'IMPORT_VAT' | 'AUSTRALIA_GST' | 'RECARGO' | 'RECARGO_REVERSE_CHARGE' | 'NEW_ZEALAND_GST' | 'SALES_TAX' - `effect` 'INCREASES_PAYOUT' | 'DEDUCTED_FROM_PAYOUT' — Whether a tax increases or decreases the payout amount. - `subtotal_after_brand_discounts` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `total_brand_discounts` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `payment_initiated_at` string — An ISO 8601 timestamp of when the brand was paid for this order. Null/absent if the order has not been paid yet. - `original_order_id` string — If this order has a parent, for example due to a backorder, this contains the ID of the original order. Null/absent otherwise. - `retailer_id` string — A unique identifier that represents the retailer who placed the order. See retailers for more information. - `source` string — How this order was initiated (may be MARKETPLACE, FAIRE_DIRECT, TRADESHOW, etc). - `expected_ship_date` string — If specified, an ISO 8601 timestamp of when the order is expected to be shipped. - `customer` ExternalOrderV2Customer - `first_name` string — The first name of the customer. - `last_name` string — The last name of the customer. - `brand_discounts` ExternalDiscountV2[] — A list of any shop-wide promotions that were applied to this order. Does not include product-specific discounts, which can be found under the `discounts` field of the relevant order item. - `id` string — A unique identifier for the discount, beginning with "bpc_". - `code` string — The name of the promotion as it appears to retailers at checkout. - `discount_type` 'FLAT_AMOUNT' | 'PERCENTAGE' | 'NONE' — The type of discount applied - either a flat amount off or a percentage off the order. - `discount_amount_cents` integer — Deprecated. Depending on discountType either discountAmountCents or discountPercentage is populated. - `discount_percentage` number — The discount amount as a percent of the total. This value is present only when the discount_type is PERCENTAGE. - `includes_free_shipping` boolean — Whether this promotion is for free shipping. - `discount_amount` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `requested_ship_date` string — An ISO 8601 timestamp of when the retailer requested the order to be shipped. - `processing_at` string — An ISO 8601 timestamp of when the order moved to PROCESSING state. - `is_free_shipping` boolean — True if the order has free shipping of any kind, false otherwise. - `free_shipping_reason` 'INSIDER_FREE_SHIPPING' | 'FAIRE_DIRECT' | 'BRAND_DISCOUNT' | 'FIRST_ORDER' | 'PROMO_CODE' | 'FREE_SHIPPING_THRESHOLD' — The reason why an order qualifies for free shipping. - `faire_covered_shipping_cost` ExternalMoneyV2 — Represents a monetary amount with currency. All monetary values in the API use this structure. The amount is stored in the smallest unit (e.g., cents for USD) to avoid floating point precision issues. - `amount_minor` integer — The amount of money in the smallest unit of the applicable currency. For example, US dollars is in cents. - `currency` string — The type of currency involved in the current payment in ISO 4217 format. For example, US dollars is USD. - `estimated_payout_at` string — An ISO 8601 timestamp of when Faire expects to pay the brand for the order. Note that this is not a guarantee of when the order will be paid out. - `is_fulfilled_by_faire` boolean — True if the order is fulfilled by Faire, false otherwise. - `purchase_order_number` string — Purchase order number entered by retailer (free-text, not validated by Faire). - `notes` string — Brand-facing notes for the order. This field is free-text and may contain special requests or instructions from the retailer. - `has_pending_retailer_cancellation_request` boolean — Indicates whether there is a pending cancellation request from the retailer for this order. This is true if the retailer has requested cancellation, the request has not been rejected, and the order is not already canceled. - `sales_rep_name` string — The name of the brand sales rep attributed to this order - `cancelled_at` string — Read-only. An ISO 8601 timestamp of when the order was canceled. Absent unless `state` is CANCELED. - `cancellation_initiated_by` string — Read-only. Who initiated the cancellation. "RETAILER" if the retailer requested it (cancel reason is REQUESTED_BY_RETAILER), "BRAND" otherwise. Absent unless `state` is CANCELED, or if the initiator is unknown. - `business_identifiers` ExternalBusinessIdentifierV2[] — Read-only. The buyer's tax and business-registration identifiers (e.g. VAT, EORI, ABN, GST), for use on invoices and customs paperwork for this order. These are the retailer's current identifiers, not a snapshot taken when the order was placed, so a value may differ from what was on file at order time. - `identifier_type` string — The type of identifier (e.g. "VAT", "EORI", "ABN", "GST"). - `identifier_value` string — The identifier value (e.g. "GB123456789"). ## Other responses - `400` — Bad Request -- Your request is invalid. - `401` — Unauthorized -- Your API key is wrong. - `404` — Not found -- The requested resource could not be found. - `405` — Method Not Allowed -- You tried to access an entity with an invalid method. - `429` — Too Many Requests. - `500` — Internal Server Error -- We had a problem with our server. Try again later. - `503` — Service Unavailable -- We're temporarily offline for maintenance. Please try again later. --- [API](https://skmtc.net/faire/apis/faire-external-api.md) · [All operations](https://skmtc.net/faire/apis/faire-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/faire/faire-external-api/revisions/19558399745c/schema)