> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/models.md). # Models ## The Error object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}}}} ``` ## The ValidationError object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}}}}} ``` ## The BasketOfferStatus object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOfferStatus":{"type":"string","description":"The lifecycle status of a basket offer.\n* `active` — eligible for application on the storefront\n* `passive` — disabled (expired offers are moved here automatically)\n* `used` — single-use offer that has been consumed; cannot be changed again\n* `revoked` — withdrawn","enum":["active","passive","used","revoked"]}}}} ``` ## The BasketOfferType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOfferType":{"type":"string","description":"How the offer is matched to a customer. See the **Offer Types** section under **Basket Offers**.","enum":["sitewide","coupon","coupon_code","voucher_code","bulk_voucher_code","bulk_coupon"]}}}} ``` ## The ConditionType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ConditionType":{"type":"string","description":"The kind of rule that decides whether the offer applies to a basket.\n* `quantity` — a minimum quantity of matching items\n* `amount` — a minimum monetary amount of matching items\n* `distinct` — a minimum number of distinct matching products\n* `query` — a free-form rule expressed only through the `query` filter list","enum":["distinct","quantity","amount","query"]}}}} ``` ## The BenefitType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BenefitType":{"type":"string","description":"What the customer receives when the condition is satisfied.\n* `percentage` — a percentage discount\n* `fixed` — a fixed-amount discount\n* `multibuy` — special pricing across a set of items (e.g. cheapest item free)\n* `shipping_free` — free shipping\n* `point` — loyalty points (legacy)\n* `coupon` — a personal coupon offer granted after purchase\n* `voucher` — a personal voucher-code offer granted after purchase\n* `sample_product` — free sample products added to the basket\n* `loyalty_point` — loyalty points credited to the customer's loyalty account","enum":["multibuy","percentage","fixed","shipping_free","point","coupon","voucher","sample_product","loyalty_point"]}}}} ``` ## The ConsumeType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ConsumeType":{"type":"string","description":"How basket items are consumed when the offer is applied.\n* `globally` — items are consumed for all offers\n* `locally` — items are consumed only within this offer\n* `whatever` — items are not consumed","enum":["globally","locally","whatever"]}}}} ``` ## The DiscountPriceType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"DiscountPriceType":{"type":"string","description":"The price used as the basis of condition and benefit calculations.","enum":["unit_price","discount_unit_price","retail_price"]}}}} ``` ## The Currency object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Currency":{"type":"string","description":"A lowercase ISO 4217 currency code (for example `try`, `usd`, `eur`)."}}}} ``` ## The Promotion object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Promotion":{"type":"object","description":"The identity of the campaign. The slug must be unique across all promotions.","required":["name"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique promotion identifier."},"name":{"type":"string","maxLength":255,"description":"Display name of the promotion."},"slug":{"type":"string","maxLength":255,"description":"Unique slug of the promotion. When omitted or blank, it is derived from the name. A duplicate slug is rejected."}}}}}} ``` ## The Condition object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Condition":{"type":"object","description":"The rule that decides whether the offer applies to a basket.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `condition_type`:\n\n| `condition_type` | Required keys in `kwargs` |\n|------------------|----------------------------|\n| `quantity` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `distinct_by`, `distinct_by_attribute_key`, `data_sources` |\n| `amount` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `data_sources` |\n| `distinct` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit` |\n| `query` | `consume_type`, `query` (must not be empty) |\n\n`query`, `sub_conditions`, and `excluded_sub_conditions` are lists of `[lookup, value]` (optionally `[lookup, value, data_type]`) pairs evaluated against basket, item, user, and pre-order attributes. `value` is the threshold quantity or amount; `overlimit`, when provided, must be greater than or equal to `value`. When `distinct_by` is `attribute`, `distinct_by_attribute_key` is required (and vice versa, `distinct_by_attribute_key` is only accepted together with `distinct_by=attribute`).\n\nAmount-based rules (`condition_type=amount` or `_amount` lookups inside the query lists) are rejected when the offer specifies more than one currency.","required":["condition_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique condition identifier."},"condition_type":{"$ref":"#/components/schemas/ConditionType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the condition is restricted to, when any."},"upsell_message":{"type":"string","maxLength":512,"description":"Optional storefront message encouraging the customer to complete the condition. When provided, it must contain the `{remaining}` placeholder."},"kwargs":{"type":"object","description":"Type-specific configuration of the condition (see the schema description)."}}},"ConditionType":{"type":"string","description":"The kind of rule that decides whether the offer applies to a basket.\n* `quantity` — a minimum quantity of matching items\n* `amount` — a minimum monetary amount of matching items\n* `distinct` — a minimum number of distinct matching products\n* `query` — a free-form rule expressed only through the `query` filter list","enum":["distinct","quantity","amount","query"]}}}} ``` ## The Benefit object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Benefit":{"type":"object","description":"What the customer receives when the condition is satisfied.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `benefit_type` (all types also accept the optional `max_discount_amount`):\n\n| `benefit_type` | Required keys in `kwargs` |\n|----------------|----------------------------|\n| `fixed` | `price_type`, `consume_type`, `amount` |\n| `percentage` | `price_type`, `consume_type`, `percentage` |\n| `multibuy` | `price_type`, `consume_type`, `item_count`, `sort_type`, `multibuy_discount_type`, plus `percentage` or `amount` depending on the discount type |\n| `shipping_free` | `price_type`, `consume_type` |\n| `coupon` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `voucher` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `sample_product` | `price_type`, `consume_type`, `allowed_quantity` |\n| `loyalty_point` | `price_type`, `consume_type`, `coupon`, `loyalty_point_coefficient`, `valid_from`, `valid_from_custom_date`, `valid_until`, `valid_until_custom_date` |\n\nFixed-amount benefits are rejected when the offer specifies more than one currency. A `shipping_free` benefit cannot be combined with payment-step conditions (`pre_order__payment_option`, `pre_order__card_info`, `pre_order__installment`).","required":["benefit_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique benefit identifier."},"benefit_type":{"$ref":"#/components/schemas/BenefitType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the benefit is restricted to, when any."},"kwargs":{"type":"object","description":"Type-specific configuration of the benefit (see the schema description)."}}},"BenefitType":{"type":"string","description":"What the customer receives when the condition is satisfied.\n* `percentage` — a percentage discount\n* `fixed` — a fixed-amount discount\n* `multibuy` — special pricing across a set of items (e.g. cheapest item free)\n* `shipping_free` — free shipping\n* `point` — loyalty points (legacy)\n* `coupon` — a personal coupon offer granted after purchase\n* `voucher` — a personal voucher-code offer granted after purchase\n* `sample_product` — free sample products added to the basket\n* `loyalty_point` — loyalty points credited to the customer's loyalty account","enum":["multibuy","percentage","fixed","shipping_free","point","coupon","voucher","sample_product","loyalty_point"]}}}} ``` ## The BasketOfferRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOfferRequest":{"type":"object","description":"The payload accepted when creating or updating a basket offer.","required":["promotion","condition","benefit","status"],"properties":{"label":{"type":["string","null"],"maxLength":512,"description":"Administrative label of the offer. Stored per language; the request language selects the translation being written."},"promotion":{"$ref":"#/components/schemas/Promotion"},"condition":{"$ref":"#/components/schemas/Condition"},"benefit":{"$ref":"#/components/schemas/Benefit"},"status":{"$ref":"#/components/schemas/BasketOfferStatus"},"offer_type":{"allOf":[{"$ref":"#/components/schemas/BasketOfferType"}],"description":"When omitted, derived from the presence of `user` and `voucher_code`."},"voucher_code":{"type":["string","null"],"maxLength":128,"description":"Voucher code redeeming the offer. Must be unique across all basket offers."},"user":{"type":["integer","null"],"description":"Identifier of the user the offer is assigned to, for personal offer types."},"is_visible":{"type":"boolean","default":true,"description":"Whether the offer is visible on the storefront."},"is_visible_on_list":{"type":"boolean","default":false,"description":"Whether the offer is visible on storefront listing pages."},"start_datetime":{"type":["string","null"],"format":"date-time","description":"Campaign start. Must precede `end_datetime`."},"end_datetime":{"type":["string","null"],"format":"date-time","description":"Campaign end. A past end date is only accepted together with `passive` status."},"priority":{"type":"integer","default":0,"description":"Application priority; offers with higher priority are evaluated first on the storefront."},"is_mergable":{"type":"boolean","default":true,"description":"When `false`, no further offers are applied to a basket after this offer."},"allowed_quantity_per_basket":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of times the offer may be applied within a single basket."},"max_usage_per_user":{"type":"integer","default":0,"description":"The maximum number of times a single user may benefit from the offer. `0` means unlimited."},"max_stock_limit":{"type":["integer","null"],"minimum":0,"description":"The maximum total number of applications across all baskets. `0` means unlimited."},"currencies":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Currency"},"description":"The currencies the offer is valid in. Defaults to the shop's default currency (see the `DEFAULT_CURRENCY` dynamic setting)."},"is_available_for_data_sources":{"type":"boolean","default":false,"description":"Whether the offer is exposed to marketplace data sources. When `true`, both the condition and the benefit must reference a static product collection."},"kwargs":{"type":["object","null"],"description":"Free-form extra configuration. When `data_source_discount_sharing_rate` is present it must be a number between 0 and 100."},"start_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — validity start, in seconds relative to activation."},"end_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — validity end, in seconds relative to activation."},"activation_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — activation delay after purchase, in seconds. Exactly one of `activation_timedelta` and `activation_date` must be provided on the inner offer."},"activation_date":{"type":["string","null"],"format":"date-time","description":"Only for inner offers embedded in coupon / voucher benefits — absolute activation moment. Exactly one of `activation_timedelta` and `activation_date` must be provided on the inner offer."},"bulk_coupon_file":{"type":"string","contentEncoding":"base64","description":"Base64-encoded CSV or spreadsheet with an `email` column, listing the users that receive personal coupons. Cannot be combined with `user`. Turns the offer into a `bulk_coupon` offer; coupons are generated asynchronously."},"bulk_email_file":{"type":["string","null"],"contentEncoding":"base64","description":"Base64-encoded file of customer emails imported into the condition as a `bulk_email__in` rule. Processing is asynchronous; the offer is passive while the file is processed."},"bulk_phone_number_file":{"type":["string","null"],"contentEncoding":"base64","description":"Base64-encoded file of customer phone numbers imported into the condition as a `bulk_phone_number__in` rule. Processing is asynchronous; the offer is passive while the file is processed."}}},"Promotion":{"type":"object","description":"The identity of the campaign. The slug must be unique across all promotions.","required":["name"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique promotion identifier."},"name":{"type":"string","maxLength":255,"description":"Display name of the promotion."},"slug":{"type":"string","maxLength":255,"description":"Unique slug of the promotion. When omitted or blank, it is derived from the name. A duplicate slug is rejected."}}},"Condition":{"type":"object","description":"The rule that decides whether the offer applies to a basket.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `condition_type`:\n\n| `condition_type` | Required keys in `kwargs` |\n|------------------|----------------------------|\n| `quantity` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `distinct_by`, `distinct_by_attribute_key`, `data_sources` |\n| `amount` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `data_sources` |\n| `distinct` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit` |\n| `query` | `consume_type`, `query` (must not be empty) |\n\n`query`, `sub_conditions`, and `excluded_sub_conditions` are lists of `[lookup, value]` (optionally `[lookup, value, data_type]`) pairs evaluated against basket, item, user, and pre-order attributes. `value` is the threshold quantity or amount; `overlimit`, when provided, must be greater than or equal to `value`. When `distinct_by` is `attribute`, `distinct_by_attribute_key` is required (and vice versa, `distinct_by_attribute_key` is only accepted together with `distinct_by=attribute`).\n\nAmount-based rules (`condition_type=amount` or `_amount` lookups inside the query lists) are rejected when the offer specifies more than one currency.","required":["condition_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique condition identifier."},"condition_type":{"$ref":"#/components/schemas/ConditionType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the condition is restricted to, when any."},"upsell_message":{"type":"string","maxLength":512,"description":"Optional storefront message encouraging the customer to complete the condition. When provided, it must contain the `{remaining}` placeholder."},"kwargs":{"type":"object","description":"Type-specific configuration of the condition (see the schema description)."}}},"ConditionType":{"type":"string","description":"The kind of rule that decides whether the offer applies to a basket.\n* `quantity` — a minimum quantity of matching items\n* `amount` — a minimum monetary amount of matching items\n* `distinct` — a minimum number of distinct matching products\n* `query` — a free-form rule expressed only through the `query` filter list","enum":["distinct","quantity","amount","query"]},"Benefit":{"type":"object","description":"What the customer receives when the condition is satisfied.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `benefit_type` (all types also accept the optional `max_discount_amount`):\n\n| `benefit_type` | Required keys in `kwargs` |\n|----------------|----------------------------|\n| `fixed` | `price_type`, `consume_type`, `amount` |\n| `percentage` | `price_type`, `consume_type`, `percentage` |\n| `multibuy` | `price_type`, `consume_type`, `item_count`, `sort_type`, `multibuy_discount_type`, plus `percentage` or `amount` depending on the discount type |\n| `shipping_free` | `price_type`, `consume_type` |\n| `coupon` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `voucher` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `sample_product` | `price_type`, `consume_type`, `allowed_quantity` |\n| `loyalty_point` | `price_type`, `consume_type`, `coupon`, `loyalty_point_coefficient`, `valid_from`, `valid_from_custom_date`, `valid_until`, `valid_until_custom_date` |\n\nFixed-amount benefits are rejected when the offer specifies more than one currency. A `shipping_free` benefit cannot be combined with payment-step conditions (`pre_order__payment_option`, `pre_order__card_info`, `pre_order__installment`).","required":["benefit_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique benefit identifier."},"benefit_type":{"$ref":"#/components/schemas/BenefitType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the benefit is restricted to, when any."},"kwargs":{"type":"object","description":"Type-specific configuration of the benefit (see the schema description)."}}},"BenefitType":{"type":"string","description":"What the customer receives when the condition is satisfied.\n* `percentage` — a percentage discount\n* `fixed` — a fixed-amount discount\n* `multibuy` — special pricing across a set of items (e.g. cheapest item free)\n* `shipping_free` — free shipping\n* `point` — loyalty points (legacy)\n* `coupon` — a personal coupon offer granted after purchase\n* `voucher` — a personal voucher-code offer granted after purchase\n* `sample_product` — free sample products added to the basket\n* `loyalty_point` — loyalty points credited to the customer's loyalty account","enum":["multibuy","percentage","fixed","shipping_free","point","coupon","voucher","sample_product","loyalty_point"]},"BasketOfferStatus":{"type":"string","description":"The lifecycle status of a basket offer.\n* `active` — eligible for application on the storefront\n* `passive` — disabled (expired offers are moved here automatically)\n* `used` — single-use offer that has been consumed; cannot be changed again\n* `revoked` — withdrawn","enum":["active","passive","used","revoked"]},"BasketOfferType":{"type":"string","description":"How the offer is matched to a customer. See the **Offer Types** section under **Basket Offers**.","enum":["sitewide","coupon","coupon_code","voucher_code","bulk_voucher_code","bulk_coupon"]},"Currency":{"type":"string","description":"A lowercase ISO 4217 currency code (for example `try`, `usd`, `eur`)."}}}} ``` ## The BasketOffer object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOffer":{"allOf":[{"$ref":"#/components/schemas/BasketOfferRequest"},{"type":"object","description":"A basket offer as returned by the API.","properties":{"pk":{"type":"integer","description":"Unique basket offer identifier."},"user":{"type":["object","null"],"description":"When the offer is assigned to a user, the user is returned expanded as an object (identifier, email, name fields) rather than as a bare identifier."},"modified_date":{"type":"string","format":"date-time","description":"The moment the offer was last modified."},"remaining_stock_limit":{"type":"integer","description":"Only present when `max_stock_limit` is positive — the number of applications still available."}}}]},"BasketOfferRequest":{"type":"object","description":"The payload accepted when creating or updating a basket offer.","required":["promotion","condition","benefit","status"],"properties":{"label":{"type":["string","null"],"maxLength":512,"description":"Administrative label of the offer. Stored per language; the request language selects the translation being written."},"promotion":{"$ref":"#/components/schemas/Promotion"},"condition":{"$ref":"#/components/schemas/Condition"},"benefit":{"$ref":"#/components/schemas/Benefit"},"status":{"$ref":"#/components/schemas/BasketOfferStatus"},"offer_type":{"allOf":[{"$ref":"#/components/schemas/BasketOfferType"}],"description":"When omitted, derived from the presence of `user` and `voucher_code`."},"voucher_code":{"type":["string","null"],"maxLength":128,"description":"Voucher code redeeming the offer. Must be unique across all basket offers."},"user":{"type":["integer","null"],"description":"Identifier of the user the offer is assigned to, for personal offer types."},"is_visible":{"type":"boolean","default":true,"description":"Whether the offer is visible on the storefront."},"is_visible_on_list":{"type":"boolean","default":false,"description":"Whether the offer is visible on storefront listing pages."},"start_datetime":{"type":["string","null"],"format":"date-time","description":"Campaign start. Must precede `end_datetime`."},"end_datetime":{"type":["string","null"],"format":"date-time","description":"Campaign end. A past end date is only accepted together with `passive` status."},"priority":{"type":"integer","default":0,"description":"Application priority; offers with higher priority are evaluated first on the storefront."},"is_mergable":{"type":"boolean","default":true,"description":"When `false`, no further offers are applied to a basket after this offer."},"allowed_quantity_per_basket":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of times the offer may be applied within a single basket."},"max_usage_per_user":{"type":"integer","default":0,"description":"The maximum number of times a single user may benefit from the offer. `0` means unlimited."},"max_stock_limit":{"type":["integer","null"],"minimum":0,"description":"The maximum total number of applications across all baskets. `0` means unlimited."},"currencies":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Currency"},"description":"The currencies the offer is valid in. Defaults to the shop's default currency (see the `DEFAULT_CURRENCY` dynamic setting)."},"is_available_for_data_sources":{"type":"boolean","default":false,"description":"Whether the offer is exposed to marketplace data sources. When `true`, both the condition and the benefit must reference a static product collection."},"kwargs":{"type":["object","null"],"description":"Free-form extra configuration. When `data_source_discount_sharing_rate` is present it must be a number between 0 and 100."},"start_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — validity start, in seconds relative to activation."},"end_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — validity end, in seconds relative to activation."},"activation_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — activation delay after purchase, in seconds. Exactly one of `activation_timedelta` and `activation_date` must be provided on the inner offer."},"activation_date":{"type":["string","null"],"format":"date-time","description":"Only for inner offers embedded in coupon / voucher benefits — absolute activation moment. Exactly one of `activation_timedelta` and `activation_date` must be provided on the inner offer."},"bulk_coupon_file":{"type":"string","contentEncoding":"base64","description":"Base64-encoded CSV or spreadsheet with an `email` column, listing the users that receive personal coupons. Cannot be combined with `user`. Turns the offer into a `bulk_coupon` offer; coupons are generated asynchronously."},"bulk_email_file":{"type":["string","null"],"contentEncoding":"base64","description":"Base64-encoded file of customer emails imported into the condition as a `bulk_email__in` rule. Processing is asynchronous; the offer is passive while the file is processed."},"bulk_phone_number_file":{"type":["string","null"],"contentEncoding":"base64","description":"Base64-encoded file of customer phone numbers imported into the condition as a `bulk_phone_number__in` rule. Processing is asynchronous; the offer is passive while the file is processed."}}},"Promotion":{"type":"object","description":"The identity of the campaign. The slug must be unique across all promotions.","required":["name"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique promotion identifier."},"name":{"type":"string","maxLength":255,"description":"Display name of the promotion."},"slug":{"type":"string","maxLength":255,"description":"Unique slug of the promotion. When omitted or blank, it is derived from the name. A duplicate slug is rejected."}}},"Condition":{"type":"object","description":"The rule that decides whether the offer applies to a basket.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `condition_type`:\n\n| `condition_type` | Required keys in `kwargs` |\n|------------------|----------------------------|\n| `quantity` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `distinct_by`, `distinct_by_attribute_key`, `data_sources` |\n| `amount` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `data_sources` |\n| `distinct` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit` |\n| `query` | `consume_type`, `query` (must not be empty) |\n\n`query`, `sub_conditions`, and `excluded_sub_conditions` are lists of `[lookup, value]` (optionally `[lookup, value, data_type]`) pairs evaluated against basket, item, user, and pre-order attributes. `value` is the threshold quantity or amount; `overlimit`, when provided, must be greater than or equal to `value`. When `distinct_by` is `attribute`, `distinct_by_attribute_key` is required (and vice versa, `distinct_by_attribute_key` is only accepted together with `distinct_by=attribute`).\n\nAmount-based rules (`condition_type=amount` or `_amount` lookups inside the query lists) are rejected when the offer specifies more than one currency.","required":["condition_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique condition identifier."},"condition_type":{"$ref":"#/components/schemas/ConditionType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the condition is restricted to, when any."},"upsell_message":{"type":"string","maxLength":512,"description":"Optional storefront message encouraging the customer to complete the condition. When provided, it must contain the `{remaining}` placeholder."},"kwargs":{"type":"object","description":"Type-specific configuration of the condition (see the schema description)."}}},"ConditionType":{"type":"string","description":"The kind of rule that decides whether the offer applies to a basket.\n* `quantity` — a minimum quantity of matching items\n* `amount` — a minimum monetary amount of matching items\n* `distinct` — a minimum number of distinct matching products\n* `query` — a free-form rule expressed only through the `query` filter list","enum":["distinct","quantity","amount","query"]},"Benefit":{"type":"object","description":"What the customer receives when the condition is satisfied.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `benefit_type` (all types also accept the optional `max_discount_amount`):\n\n| `benefit_type` | Required keys in `kwargs` |\n|----------------|----------------------------|\n| `fixed` | `price_type`, `consume_type`, `amount` |\n| `percentage` | `price_type`, `consume_type`, `percentage` |\n| `multibuy` | `price_type`, `consume_type`, `item_count`, `sort_type`, `multibuy_discount_type`, plus `percentage` or `amount` depending on the discount type |\n| `shipping_free` | `price_type`, `consume_type` |\n| `coupon` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `voucher` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `sample_product` | `price_type`, `consume_type`, `allowed_quantity` |\n| `loyalty_point` | `price_type`, `consume_type`, `coupon`, `loyalty_point_coefficient`, `valid_from`, `valid_from_custom_date`, `valid_until`, `valid_until_custom_date` |\n\nFixed-amount benefits are rejected when the offer specifies more than one currency. A `shipping_free` benefit cannot be combined with payment-step conditions (`pre_order__payment_option`, `pre_order__card_info`, `pre_order__installment`).","required":["benefit_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique benefit identifier."},"benefit_type":{"$ref":"#/components/schemas/BenefitType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the benefit is restricted to, when any."},"kwargs":{"type":"object","description":"Type-specific configuration of the benefit (see the schema description)."}}},"BenefitType":{"type":"string","description":"What the customer receives when the condition is satisfied.\n* `percentage` — a percentage discount\n* `fixed` — a fixed-amount discount\n* `multibuy` — special pricing across a set of items (e.g. cheapest item free)\n* `shipping_free` — free shipping\n* `point` — loyalty points (legacy)\n* `coupon` — a personal coupon offer granted after purchase\n* `voucher` — a personal voucher-code offer granted after purchase\n* `sample_product` — free sample products added to the basket\n* `loyalty_point` — loyalty points credited to the customer's loyalty account","enum":["multibuy","percentage","fixed","shipping_free","point","coupon","voucher","sample_product","loyalty_point"]},"BasketOfferStatus":{"type":"string","description":"The lifecycle status of a basket offer.\n* `active` — eligible for application on the storefront\n* `passive` — disabled (expired offers are moved here automatically)\n* `used` — single-use offer that has been consumed; cannot be changed again\n* `revoked` — withdrawn","enum":["active","passive","used","revoked"]},"BasketOfferType":{"type":"string","description":"How the offer is matched to a customer. See the **Offer Types** section under **Basket Offers**.","enum":["sitewide","coupon","coupon_code","voucher_code","bulk_voucher_code","bulk_coupon"]},"Currency":{"type":"string","description":"A lowercase ISO 4217 currency code (for example `try`, `usd`, `eur`)."}}}} ``` ## The BasketOfferSetStatusRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOfferSetStatusRequest":{"type":"object","required":["status"],"properties":{"status":{"allOf":[{"$ref":"#/components/schemas/BasketOfferStatus"}],"description":"The new status. An offer whose current status is `used` cannot be changed."}}},"BasketOfferStatus":{"type":"string","description":"The lifecycle status of a basket offer.\n* `active` — eligible for application on the storefront\n* `passive` — disabled (expired offers are moved here automatically)\n* `used` — single-use offer that has been consumed; cannot be changed again\n* `revoked` — withdrawn","enum":["active","passive","used","revoked"]}}}} ``` ## The BasketOfferBulkSetStatusRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOfferBulkSetStatusRequest":{"type":"object","required":["basket_offers","status"],"properties":{"basket_offers":{"type":"array","items":{"type":"integer"},"description":"Identifiers of the basket offers to change. Only offers whose current status is `active` or `passive` are accepted."},"status":{"type":"string","enum":["active","passive"],"description":"The status applied to every targeted offer."}}}}}} ``` ## The PaginatedBasketOfferList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedBasketOfferList":{"type":"object","description":"A page of basket offer results.","properties":{"count":{"type":"integer","description":"The total number of basket offers matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The basket offers on the current page.","items":{"$ref":"#/components/schemas/BasketOffer"}}}},"BasketOffer":{"allOf":[{"$ref":"#/components/schemas/BasketOfferRequest"},{"type":"object","description":"A basket offer as returned by the API.","properties":{"pk":{"type":"integer","description":"Unique basket offer identifier."},"user":{"type":["object","null"],"description":"When the offer is assigned to a user, the user is returned expanded as an object (identifier, email, name fields) rather than as a bare identifier."},"modified_date":{"type":"string","format":"date-time","description":"The moment the offer was last modified."},"remaining_stock_limit":{"type":"integer","description":"Only present when `max_stock_limit` is positive — the number of applications still available."}}}]},"BasketOfferRequest":{"type":"object","description":"The payload accepted when creating or updating a basket offer.","required":["promotion","condition","benefit","status"],"properties":{"label":{"type":["string","null"],"maxLength":512,"description":"Administrative label of the offer. Stored per language; the request language selects the translation being written."},"promotion":{"$ref":"#/components/schemas/Promotion"},"condition":{"$ref":"#/components/schemas/Condition"},"benefit":{"$ref":"#/components/schemas/Benefit"},"status":{"$ref":"#/components/schemas/BasketOfferStatus"},"offer_type":{"allOf":[{"$ref":"#/components/schemas/BasketOfferType"}],"description":"When omitted, derived from the presence of `user` and `voucher_code`."},"voucher_code":{"type":["string","null"],"maxLength":128,"description":"Voucher code redeeming the offer. Must be unique across all basket offers."},"user":{"type":["integer","null"],"description":"Identifier of the user the offer is assigned to, for personal offer types."},"is_visible":{"type":"boolean","default":true,"description":"Whether the offer is visible on the storefront."},"is_visible_on_list":{"type":"boolean","default":false,"description":"Whether the offer is visible on storefront listing pages."},"start_datetime":{"type":["string","null"],"format":"date-time","description":"Campaign start. Must precede `end_datetime`."},"end_datetime":{"type":["string","null"],"format":"date-time","description":"Campaign end. A past end date is only accepted together with `passive` status."},"priority":{"type":"integer","default":0,"description":"Application priority; offers with higher priority are evaluated first on the storefront."},"is_mergable":{"type":"boolean","default":true,"description":"When `false`, no further offers are applied to a basket after this offer."},"allowed_quantity_per_basket":{"type":"integer","minimum":1,"default":1,"description":"The maximum number of times the offer may be applied within a single basket."},"max_usage_per_user":{"type":"integer","default":0,"description":"The maximum number of times a single user may benefit from the offer. `0` means unlimited."},"max_stock_limit":{"type":["integer","null"],"minimum":0,"description":"The maximum total number of applications across all baskets. `0` means unlimited."},"currencies":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Currency"},"description":"The currencies the offer is valid in. Defaults to the shop's default currency (see the `DEFAULT_CURRENCY` dynamic setting)."},"is_available_for_data_sources":{"type":"boolean","default":false,"description":"Whether the offer is exposed to marketplace data sources. When `true`, both the condition and the benefit must reference a static product collection."},"kwargs":{"type":["object","null"],"description":"Free-form extra configuration. When `data_source_discount_sharing_rate` is present it must be a number between 0 and 100."},"start_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — validity start, in seconds relative to activation."},"end_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — validity end, in seconds relative to activation."},"activation_timedelta":{"type":["integer","null"],"minimum":0,"description":"Only for inner offers embedded in coupon / voucher benefits — activation delay after purchase, in seconds. Exactly one of `activation_timedelta` and `activation_date` must be provided on the inner offer."},"activation_date":{"type":["string","null"],"format":"date-time","description":"Only for inner offers embedded in coupon / voucher benefits — absolute activation moment. Exactly one of `activation_timedelta` and `activation_date` must be provided on the inner offer."},"bulk_coupon_file":{"type":"string","contentEncoding":"base64","description":"Base64-encoded CSV or spreadsheet with an `email` column, listing the users that receive personal coupons. Cannot be combined with `user`. Turns the offer into a `bulk_coupon` offer; coupons are generated asynchronously."},"bulk_email_file":{"type":["string","null"],"contentEncoding":"base64","description":"Base64-encoded file of customer emails imported into the condition as a `bulk_email__in` rule. Processing is asynchronous; the offer is passive while the file is processed."},"bulk_phone_number_file":{"type":["string","null"],"contentEncoding":"base64","description":"Base64-encoded file of customer phone numbers imported into the condition as a `bulk_phone_number__in` rule. Processing is asynchronous; the offer is passive while the file is processed."}}},"Promotion":{"type":"object","description":"The identity of the campaign. The slug must be unique across all promotions.","required":["name"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique promotion identifier."},"name":{"type":"string","maxLength":255,"description":"Display name of the promotion."},"slug":{"type":"string","maxLength":255,"description":"Unique slug of the promotion. When omitted or blank, it is derived from the name. A duplicate slug is rejected."}}},"Condition":{"type":"object","description":"The rule that decides whether the offer applies to a basket.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `condition_type`:\n\n| `condition_type` | Required keys in `kwargs` |\n|------------------|----------------------------|\n| `quantity` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `distinct_by`, `distinct_by_attribute_key`, `data_sources` |\n| `amount` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `data_sources` |\n| `distinct` | `price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit` |\n| `query` | `consume_type`, `query` (must not be empty) |\n\n`query`, `sub_conditions`, and `excluded_sub_conditions` are lists of `[lookup, value]` (optionally `[lookup, value, data_type]`) pairs evaluated against basket, item, user, and pre-order attributes. `value` is the threshold quantity or amount; `overlimit`, when provided, must be greater than or equal to `value`. When `distinct_by` is `attribute`, `distinct_by_attribute_key` is required (and vice versa, `distinct_by_attribute_key` is only accepted together with `distinct_by=attribute`).\n\nAmount-based rules (`condition_type=amount` or `_amount` lookups inside the query lists) are rejected when the offer specifies more than one currency.","required":["condition_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique condition identifier."},"condition_type":{"$ref":"#/components/schemas/ConditionType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the condition is restricted to, when any."},"upsell_message":{"type":"string","maxLength":512,"description":"Optional storefront message encouraging the customer to complete the condition. When provided, it must contain the `{remaining}` placeholder."},"kwargs":{"type":"object","description":"Type-specific configuration of the condition (see the schema description)."}}},"ConditionType":{"type":"string","description":"The kind of rule that decides whether the offer applies to a basket.\n* `quantity` — a minimum quantity of matching items\n* `amount` — a minimum monetary amount of matching items\n* `distinct` — a minimum number of distinct matching products\n* `query` — a free-form rule expressed only through the `query` filter list","enum":["distinct","quantity","amount","query"]},"Benefit":{"type":"object","description":"What the customer receives when the condition is satisfied.\n\nThe `kwargs` object carries the type-specific configuration. Required keys per `benefit_type` (all types also accept the optional `max_discount_amount`):\n\n| `benefit_type` | Required keys in `kwargs` |\n|----------------|----------------------------|\n| `fixed` | `price_type`, `consume_type`, `amount` |\n| `percentage` | `price_type`, `consume_type`, `percentage` |\n| `multibuy` | `price_type`, `consume_type`, `item_count`, `sort_type`, `multibuy_discount_type`, plus `percentage` or `amount` depending on the discount type |\n| `shipping_free` | `price_type`, `consume_type` |\n| `coupon` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `voucher` | `price_type`, `consume_type`, `coupon` (an inner basket offer definition) |\n| `sample_product` | `price_type`, `consume_type`, `allowed_quantity` |\n| `loyalty_point` | `price_type`, `consume_type`, `coupon`, `loyalty_point_coefficient`, `valid_from`, `valid_from_custom_date`, `valid_until`, `valid_until_custom_date` |\n\nFixed-amount benefits are rejected when the offer specifies more than one currency. A `shipping_free` benefit cannot be combined with payment-step conditions (`pre_order__payment_option`, `pre_order__card_info`, `pre_order__installment`).","required":["benefit_type","kwargs"],"properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique benefit identifier."},"benefit_type":{"$ref":"#/components/schemas/BenefitType"},"product_collection":{"type":["integer","null"],"description":"Identifier of the product collection the benefit is restricted to, when any."},"kwargs":{"type":"object","description":"Type-specific configuration of the benefit (see the schema description)."}}},"BenefitType":{"type":"string","description":"What the customer receives when the condition is satisfied.\n* `percentage` — a percentage discount\n* `fixed` — a fixed-amount discount\n* `multibuy` — special pricing across a set of items (e.g. cheapest item free)\n* `shipping_free` — free shipping\n* `point` — loyalty points (legacy)\n* `coupon` — a personal coupon offer granted after purchase\n* `voucher` — a personal voucher-code offer granted after purchase\n* `sample_product` — free sample products added to the basket\n* `loyalty_point` — loyalty points credited to the customer's loyalty account","enum":["multibuy","percentage","fixed","shipping_free","point","coupon","voucher","sample_product","loyalty_point"]},"BasketOfferStatus":{"type":"string","description":"The lifecycle status of a basket offer.\n* `active` — eligible for application on the storefront\n* `passive` — disabled (expired offers are moved here automatically)\n* `used` — single-use offer that has been consumed; cannot be changed again\n* `revoked` — withdrawn","enum":["active","passive","used","revoked"]},"BasketOfferType":{"type":"string","description":"How the offer is matched to a customer. See the **Offer Types** section under **Basket Offers**.","enum":["sitewide","coupon","coupon_code","voucher_code","bulk_voucher_code","bulk_coupon"]},"Currency":{"type":"string","description":"A lowercase ISO 4217 currency code (for example `try`, `usd`, `eur`)."}}}} ``` ## The BasketOfferBusinessError object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BasketOfferBusinessError":{"type":"object","description":"Returned when a request is valid in form but violates a business rule of the promotion engine. The message describes the rule that was violated, and a stable code identifies it.\n\nCodes raised by these endpoints:\n* `promotion_100_1` — a promotion with the same slug already exists.\n* `promotion_100_2` — a basket offer with the same voucher code already exists.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}}}} ``` ## The VoucherCodeStatus object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"VoucherCodeStatus":{"type":"string","description":"The lifecycle status of a voucher code.\n* `active` — the code can be redeemed; new codes always start here\n* `passive` — the code is disabled\n* `used` — the code has been redeemed and can no longer be updated\n* `revoked` — the code has been withdrawn","enum":["active","passive","used","revoked"]}}}} ``` ## The BulkVoucherCodeRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BulkVoucherCodeRequest":{"type":"object","description":"The payload accepted when creating or updating a bulk voucher code.","required":["code","basket_offer","status"],"properties":{"code":{"type":"string","maxLength":32,"description":"The voucher code value. Must be unique across all bulk voucher codes."},"basket_offer":{"type":"integer","description":"Identifier of the parent basket offer."},"status":{"allOf":[{"$ref":"#/components/schemas/VoucherCodeStatus"}],"description":"The code status. On **create** this value is ignored — new codes are always created as `active`. On **update** it activates (`active`) or deactivates (`passive`) the code."},"user":{"type":["integer","null"],"description":"Identifier of the user the code is assigned to, when any. A user can hold at most one code per basket offer."}}},"VoucherCodeStatus":{"type":"string","description":"The lifecycle status of a voucher code.\n* `active` — the code can be redeemed; new codes always start here\n* `passive` — the code is disabled\n* `used` — the code has been redeemed and can no longer be updated\n* `revoked` — the code has been withdrawn","enum":["active","passive","used","revoked"]}}}} ``` ## The BulkVoucherCode object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BulkVoucherCode":{"type":"object","description":"A bulk voucher code as returned by the API.","properties":{"pk":{"type":"integer","description":"Unique voucher code identifier."},"code":{"type":"string","description":"The voucher code value."},"basket_offer":{"type":"integer","description":"Identifier of the parent basket offer."},"status":{"$ref":"#/components/schemas/VoucherCodeStatus"},"user":{"type":["integer","null"],"description":"Identifier of the user the code is assigned to, when any."},"user_email":{"type":["string","null"],"description":"Email address of the assigned user, when any."}}},"VoucherCodeStatus":{"type":"string","description":"The lifecycle status of a voucher code.\n* `active` — the code can be redeemed; new codes always start here\n* `passive` — the code is disabled\n* `used` — the code has been redeemed and can no longer be updated\n* `revoked` — the code has been withdrawn","enum":["active","passive","used","revoked"]}}}} ``` ## The BulkVoucherCodeBulkCreateRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BulkVoucherCodeBulkCreateRequest":{"type":"object","description":"The payload of a bulk code generation request.","required":["prefix","count","basket_offer"],"properties":{"basket_offer":{"type":"integer","description":"Identifier of the target basket offer. The offer must be of type `bulk_voucher_code` and in `active` status."},"count":{"type":"integer","minimum":1,"description":"The number of codes to generate."},"prefix":{"type":"string","minLength":2,"description":"The fixed prefix every generated code starts with."},"alphabet":{"type":"string","minLength":1,"default":"ABCDEF0123456789","description":"The characters the random part of the codes is drawn from. Only uppercase English letters and digits are allowed; duplicate characters are collapsed."},"length":{"type":"integer","minimum":1,"default":8,"description":"The length of the random part appended to the prefix. `prefix` + `length` must not exceed 32 characters."}}}}}} ``` ## The BulkVoucherCodeSheetImportRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BulkVoucherCodeSheetImportRequest":{"type":"object","description":"The payload of a spreadsheet import request.","required":["basket_offer","file"],"properties":{"basket_offer":{"type":"integer","description":"Identifier of the target basket offer. The offer must be of type `bulk_voucher_code`."},"file":{"type":"string","contentEncoding":"base64","description":"Base64-encoded Excel or CSV file with exactly the column headers `voucher_code` and `user_email`."}}}}}} ``` ## The ExcelExportStatus object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ExcelExportStatus":{"type":"object","description":"The status envelope of an asynchronous Excel export.","properties":{"cache_key":{"type":"string","format":"uuid","description":"The job key used to poll the export status."},"is_ready":{"type":"boolean","description":"Whether the export file is ready for download."},"url":{"type":["string","null"],"format":"uri","description":"The download URL of the generated file, present once `is_ready` is `true`."},"error_message":{"type":["string","null"],"description":"A human-readable error message when the export failed or was not found."}}}}}} ``` ## The ExcelImportStatus object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ExcelImportStatus":{"type":"object","description":"The status envelope of an asynchronous Excel/CSV import.","properties":{"cache_key":{"type":"string","format":"uuid","description":"The job key used to poll the import status."},"is_ready":{"type":"boolean","description":"Whether the import has finished."},"result":{"type":["object","null"],"description":"The import result, present once `is_ready` is `true`.","properties":{"assigned_count":{"type":"integer","description":"The number of codes created or assigned successfully."},"errors":{"type":"array","description":"One entry for every skipped row.","items":{"type":"object","properties":{"voucher_code":{"type":"string","description":"The code value of the skipped row."},"user_email":{"type":"string","description":"The email of the skipped row."},"error":{"type":"string","description":"Why the row was skipped."}}}},"summary":{"type":"object","description":"Aggregate counts of the import.","properties":{"total_rows":{"type":"integer","description":"The total number of rows in the file."},"successful":{"type":"integer","description":"The number of rows processed successfully."},"failed":{"type":"integer","description":"The number of rows skipped with an error."}}}}},"error_message":{"type":["string","null"],"description":"A human-readable error message when the import failed or was not found."}}}}}} ``` ## The PaginatedBulkVoucherCodeList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedBulkVoucherCodeList":{"type":"object","description":"A page of bulk voucher code results.","properties":{"count":{"type":"integer","description":"The total number of voucher codes matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The voucher codes on the current page.","items":{"$ref":"#/components/schemas/BulkVoucherCode"}}}},"BulkVoucherCode":{"type":"object","description":"A bulk voucher code as returned by the API.","properties":{"pk":{"type":"integer","description":"Unique voucher code identifier."},"code":{"type":"string","description":"The voucher code value."},"basket_offer":{"type":"integer","description":"Identifier of the parent basket offer."},"status":{"$ref":"#/components/schemas/VoucherCodeStatus"},"user":{"type":["integer","null"],"description":"Identifier of the user the code is assigned to, when any."},"user_email":{"type":["string","null"],"description":"Email address of the assigned user, when any."}}},"VoucherCodeStatus":{"type":"string","description":"The lifecycle status of a voucher code.\n* `active` — the code can be redeemed; new codes always start here\n* `passive` — the code is disabled\n* `used` — the code has been redeemed and can no longer be updated\n* `revoked` — the code has been withdrawn","enum":["active","passive","used","revoked"]}}}} ``` ## The BulkVoucherCodeBusinessError object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"BulkVoucherCodeBusinessError":{"type":"object","description":"Returned when a request is valid in form but violates a business rule of the promotion engine. The message describes the rule that was violated, and a stable code identifies it.\n\nCodes raised by these endpoints:\n* `promotion_100_2` — a voucher code with the same value already exists.\n* `promotion_100_5` — a used voucher code cannot be updated.\n* `promotion_100_6` — the user already holds a voucher code for this basket offer.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}}}} ``` ## The ProductType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductType":{"type":"string","description":"The product type. The value is the numeric code as a string.\n* `-1` — Pre Product\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `-2` — Pre Miscellaneous\n* `4` — Miscellaneous\n* `5` — Offer","enum":["-1","0","1","2","3","-2","4","5"]}}}} ``` ## The WritableProductType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"WritableProductType":{"type":"string","description":"The product type accepted when creating or updating a product. The value is the numeric code as a string.\n\nThe draft types Pre Product (`-1`) and Pre Miscellaneous (`-2`) are not accepted here; they are used only for products created through other processes.\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `4` — Miscellaneous\n* `5` — Offer","enum":["0","1","2","3","4","5"]}}}} ``` ## The ProductImage object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductImage":{"type":"object","description":"An image attached to the product.","properties":{"pk":{"type":"integer","readOnly":true},"status":{"type":"string","description":"The processing status of the image.","readOnly":true},"image":{"type":"string","description":"The image file path."},"order":{"type":"integer","description":"The display order of the image."},"created_date":{"type":"string","format":"date-time","description":"The date and time the image was created.","readOnly":true},"specialimage_set":{"type":"array","description":"Special image variants associated with the image.","items":{"type":"object"}}}}}}} ``` ## The Product object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Product":{"type":"object","description":"A product in the catalog.","properties":{"pk":{"type":"integer","description":"The unique identifier of the product.","readOnly":true},"name":{"type":"string","description":"The product name."},"base_code":{"type":["string","null"],"description":"The base code shared by variants of the same product."},"sku":{"type":"string","description":"The unique stock keeping unit."},"product_type":{"$ref":"#/components/schemas/ProductType"},"is_active":{"type":"boolean","description":"Whether the product is active."},"parent":{"type":["integer","null"],"description":"The identifier of the parent product, when the product is a variant."},"attributes":{"type":"object","description":"The attribute values of the product, keyed by attribute name.","additionalProperties":true},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata for the product.","additionalProperties":true},"extra_attributes":{"type":"object","description":"Free-form extra attribute data for the product.","additionalProperties":true},"is_seller_product":{"type":"boolean","description":"Whether the product belongs to a seller."},"group_products":{"type":["array","null"],"description":"The identifiers of products grouped under this product.","items":{"type":"integer"}},"productimage_set":{"type":"array","description":"The images attached to the product.","readOnly":true,"items":{"$ref":"#/components/schemas/ProductImage"}},"attribute_set":{"type":"integer","description":"The identifier of the attribute set that defines the product's attributes."},"custom_attribute_set":{"type":["integer","null"],"description":"The identifier of an additional custom attribute set."},"is_listable":{"type":"boolean","description":"Whether the product is publicly listable. Determined by the system.","readOnly":true},"listing_code":{"type":["string","null"],"description":"The code that identifies the listable variant grouping."},"data_source":{"type":["integer","null"],"description":"The identifier of the default data source (seller) for the product."},"absolute_url":{"type":["string","null"],"description":"The storefront URL of the product, when available.","readOnly":true},"is_form_required":{"type":"boolean","description":"Whether the product requires form input."}}},"ProductType":{"type":"string","description":"The product type. The value is the numeric code as a string.\n* `-1` — Pre Product\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `-2` — Pre Miscellaneous\n* `4` — Miscellaneous\n* `5` — Offer","enum":["-1","0","1","2","3","-2","4","5"]},"ProductImage":{"type":"object","description":"An image attached to the product.","properties":{"pk":{"type":"integer","readOnly":true},"status":{"type":"string","description":"The processing status of the image.","readOnly":true},"image":{"type":"string","description":"The image file path."},"order":{"type":"integer","description":"The display order of the image."},"created_date":{"type":"string","format":"date-time","description":"The date and time the image was created.","readOnly":true},"specialimage_set":{"type":"array","description":"Special image variants associated with the image.","items":{"type":"object"}}}}}}} ``` ## The ProductWriteRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductWriteRequest":{"type":"object","description":"The data used to create or fully update a product.","required":["name","sku","product_type","attribute_set","extra_attributes"],"properties":{"name":{"type":"string","description":"The product name."},"base_code":{"type":["string","null"],"description":"The base code shared by variants of the same product."},"sku":{"type":"string","description":"The unique stock keeping unit."},"product_type":{"$ref":"#/components/schemas/WritableProductType"},"is_active":{"type":"boolean","default":true,"description":"Whether the product is active."},"parent":{"type":["integer","null"],"description":"The identifier of the parent product. Required for offer products."},"attributes":{"type":"object","description":"The attribute values of the product, keyed by attribute name.","additionalProperties":true},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata for the product.","additionalProperties":true},"extra_attributes":{"type":"object","description":"Free-form extra attribute data for the product.","additionalProperties":true},"is_seller_product":{"type":"boolean","default":false,"description":"Whether the product belongs to a seller."},"group_products":{"type":["array","null"],"description":"The identifiers of products to group under this product.","items":{"type":"integer"}},"attribute_set":{"type":"integer","description":"The identifier of the attribute set that defines the product's attributes."},"custom_attribute_set":{"type":["integer","null"],"description":"The identifier of an additional custom attribute set."},"localized_attributes":{"type":"object","description":"Attribute values provided per language. Not returned in responses.","additionalProperties":true},"localized_attributes_kwargs":{"type":"object","description":"Additional per-language attribute metadata. Not returned in responses.","additionalProperties":true},"listing_code":{"type":["string","null"],"description":"The code that identifies the listable variant grouping."},"data_source":{"type":["integer","null"],"description":"The identifier of the default data source (seller). Required for offer products."},"is_form_required":{"type":"boolean","description":"Whether the product requires form input. This value is determined automatically by the system from the attribute set and product type; any value you send is ignored."}}},"WritableProductType":{"type":"string","description":"The product type accepted when creating or updating a product. The value is the numeric code as a string.\n\nThe draft types Pre Product (`-1`) and Pre Miscellaneous (`-2`) are not accepted here; they are used only for products created through other processes.\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `4` — Miscellaneous\n* `5` — Offer","enum":["0","1","2","3","4","5"]}}}} ``` ## The ProductPatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductPatchRequest":{"type":"object","description":"A partial set of product fields to update. Only the provided fields are changed.","properties":{"name":{"type":"string","description":"The product name."},"base_code":{"type":["string","null"],"description":"The base code shared by variants of the same product."},"sku":{"type":"string","description":"The unique stock keeping unit."},"product_type":{"$ref":"#/components/schemas/WritableProductType"},"is_active":{"type":"boolean","description":"Whether the product is active."},"parent":{"type":["integer","null"],"description":"The identifier of the parent product."},"attributes":{"type":"object","description":"The attribute values of the product, keyed by attribute name.","additionalProperties":true},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata for the product.","additionalProperties":true},"extra_attributes":{"type":"object","description":"Free-form extra attribute data for the product.","additionalProperties":true},"is_seller_product":{"type":"boolean","description":"Whether the product belongs to a seller."},"group_products":{"type":["array","null"],"description":"The identifiers of products to group under this product.","items":{"type":"integer"}},"attribute_set":{"type":"integer","description":"The identifier of the attribute set that defines the product's attributes."},"custom_attribute_set":{"type":["integer","null"],"description":"The identifier of an additional custom attribute set."},"localized_attributes":{"type":"object","description":"Attribute values provided per language. Not returned in responses.","additionalProperties":true},"localized_attributes_kwargs":{"type":"object","description":"Additional per-language attribute metadata. Not returned in responses.","additionalProperties":true},"listing_code":{"type":["string","null"],"description":"The code that identifies the listable variant grouping."},"data_source":{"type":["integer","null"],"description":"The identifier of the default data source (seller)."},"is_form_required":{"type":"boolean","description":"Whether the product requires form input. This value is determined automatically by the system from the attribute set and product type; any value you send is ignored."}}},"WritableProductType":{"type":"string","description":"The product type accepted when creating or updating a product. The value is the numeric code as a string.\n\nThe draft types Pre Product (`-1`) and Pre Miscellaneous (`-2`) are not accepted here; they are used only for products created through other processes.\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `4` — Miscellaneous\n* `5` — Offer","enum":["0","1","2","3","4","5"]}}}} ``` ## The PaginatedProductList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedProductList":{"type":"object","description":"A page of product results.","properties":{"count":{"type":"integer","description":"The total number of products matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The products on the current page.","items":{"$ref":"#/components/schemas/Product"}}}},"Product":{"type":"object","description":"A product in the catalog.","properties":{"pk":{"type":"integer","description":"The unique identifier of the product.","readOnly":true},"name":{"type":"string","description":"The product name."},"base_code":{"type":["string","null"],"description":"The base code shared by variants of the same product."},"sku":{"type":"string","description":"The unique stock keeping unit."},"product_type":{"$ref":"#/components/schemas/ProductType"},"is_active":{"type":"boolean","description":"Whether the product is active."},"parent":{"type":["integer","null"],"description":"The identifier of the parent product, when the product is a variant."},"attributes":{"type":"object","description":"The attribute values of the product, keyed by attribute name.","additionalProperties":true},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata for the product.","additionalProperties":true},"extra_attributes":{"type":"object","description":"Free-form extra attribute data for the product.","additionalProperties":true},"is_seller_product":{"type":"boolean","description":"Whether the product belongs to a seller."},"group_products":{"type":["array","null"],"description":"The identifiers of products grouped under this product.","items":{"type":"integer"}},"productimage_set":{"type":"array","description":"The images attached to the product.","readOnly":true,"items":{"$ref":"#/components/schemas/ProductImage"}},"attribute_set":{"type":"integer","description":"The identifier of the attribute set that defines the product's attributes."},"custom_attribute_set":{"type":["integer","null"],"description":"The identifier of an additional custom attribute set."},"is_listable":{"type":"boolean","description":"Whether the product is publicly listable. Determined by the system.","readOnly":true},"listing_code":{"type":["string","null"],"description":"The code that identifies the listable variant grouping."},"data_source":{"type":["integer","null"],"description":"The identifier of the default data source (seller) for the product."},"absolute_url":{"type":["string","null"],"description":"The storefront URL of the product, when available.","readOnly":true},"is_form_required":{"type":"boolean","description":"Whether the product requires form input."}}},"ProductType":{"type":"string","description":"The product type. The value is the numeric code as a string.\n* `-1` — Pre Product\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `-2` — Pre Miscellaneous\n* `4` — Miscellaneous\n* `5` — Offer","enum":["-1","0","1","2","3","-2","4","5"]},"ProductImage":{"type":"object","description":"An image attached to the product.","properties":{"pk":{"type":"integer","readOnly":true},"status":{"type":"string","description":"The processing status of the image.","readOnly":true},"image":{"type":"string","description":"The image file path."},"order":{"type":"integer","description":"The display order of the image."},"created_date":{"type":"string","format":"date-time","description":"The date and time the image was created.","readOnly":true},"specialimage_set":{"type":"array","description":"Special image variants associated with the image.","items":{"type":"object"}}}}}}} ``` ## The ProductAdvanced object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductAdvanced":{"type":"object","description":"An active simple product with segment-aware price, stock, currency, main category, first image, and variant attribute values.","required":["pk","name","base_code","sku","product_type","is_active","price","currency","stock","variants"],"properties":{"pk":{"type":"integer","description":"Unique product identifier."},"name":{"type":"string","description":"Display name of the product."},"base_code":{"type":"string","description":"Base product code shared across all variants of the same product."},"sku":{"type":"string","description":"Stock Keeping Unit — unique code for this specific variant."},"product_type":{"allOf":[{"$ref":"#/components/schemas/ProductType"}],"description":"Product type code. Always `\"0\"` (simple) for this endpoint; the queryset is pre-filtered to simple products only."},"is_active":{"type":"boolean","description":"Whether the product is active. Always `true` for this endpoint."},"price":{"type":"string","description":"Current selling price as a decimal string.\n\nWhen a `segment` is provided, this is the price from the segment's price list. When the product has no entry on the requested price list, `\"0.00\"` is returned. When no segment is provided, the product's default price is returned."},"currency":{"type":"string","description":"Currency code for `price`.\n\nWhen a `segment` is provided, this is the currency of the segment's price list. When no segment is provided, the product's own `currency_type` is returned."},"stock":{"type":"integer","description":"Available stock quantity.\n\nWhen a `segment` is provided, this is the stock from the segment's stock list. When the product has no entry on the requested stock list, `0` is returned. When no segment is provided, the product's default stock is returned."},"category":{"type":["string","null"],"description":"Name of the product's main category. `null` when no main category is set."},"product_image":{"type":["string","null"],"format":"uri","description":"URL of the product's first image. `null` when the product has no images."},"variants":{"type":"object","description":"Variant attribute values for this product as a flat key/value map, where each key is an attribute name and the value is the product's value for that attribute.\n\nThe keys present depend on the product's attribute set configuration.","additionalProperties":true}}},"ProductType":{"type":"string","description":"The product type. The value is the numeric code as a string.\n* `-1` — Pre Product\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `-2` — Pre Miscellaneous\n* `4` — Miscellaneous\n* `5` — Offer","enum":["-1","0","1","2","3","-2","4","5"]}}}} ``` ## The ProductAdvancedList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductAdvancedList":{"type":"object","description":"Paginated list of advanced product representations.","required":["count","results"],"properties":{"count":{"type":"integer","description":"Total number of products matching the current filters."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The products on the current page.","items":{"$ref":"#/components/schemas/ProductAdvanced"}}}},"ProductAdvanced":{"type":"object","description":"An active simple product with segment-aware price, stock, currency, main category, first image, and variant attribute values.","required":["pk","name","base_code","sku","product_type","is_active","price","currency","stock","variants"],"properties":{"pk":{"type":"integer","description":"Unique product identifier."},"name":{"type":"string","description":"Display name of the product."},"base_code":{"type":"string","description":"Base product code shared across all variants of the same product."},"sku":{"type":"string","description":"Stock Keeping Unit — unique code for this specific variant."},"product_type":{"allOf":[{"$ref":"#/components/schemas/ProductType"}],"description":"Product type code. Always `\"0\"` (simple) for this endpoint; the queryset is pre-filtered to simple products only."},"is_active":{"type":"boolean","description":"Whether the product is active. Always `true` for this endpoint."},"price":{"type":"string","description":"Current selling price as a decimal string.\n\nWhen a `segment` is provided, this is the price from the segment's price list. When the product has no entry on the requested price list, `\"0.00\"` is returned. When no segment is provided, the product's default price is returned."},"currency":{"type":"string","description":"Currency code for `price`.\n\nWhen a `segment` is provided, this is the currency of the segment's price list. When no segment is provided, the product's own `currency_type` is returned."},"stock":{"type":"integer","description":"Available stock quantity.\n\nWhen a `segment` is provided, this is the stock from the segment's stock list. When the product has no entry on the requested stock list, `0` is returned. When no segment is provided, the product's default stock is returned."},"category":{"type":["string","null"],"description":"Name of the product's main category. `null` when no main category is set."},"product_image":{"type":["string","null"],"format":"uri","description":"URL of the product's first image. `null` when the product has no images."},"variants":{"type":"object","description":"Variant attribute values for this product as a flat key/value map, where each key is an attribute name and the value is the product's value for that attribute.\n\nThe keys present depend on the product's attribute set configuration.","additionalProperties":true}}},"ProductType":{"type":"string","description":"The product type. The value is the numeric code as a string.\n* `-1` — Pre Product\n* `0` — Simple\n* `1` — Product Meta\n* `2` — Bundle\n* `3` — Grouped\n* `-2` — Pre Miscellaneous\n* `4` — Miscellaneous\n* `5` — Offer","enum":["-1","0","1","2","3","-2","4","5"]}}}} ``` ## The ProductBusinessError object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ProductBusinessError":{"type":"object","description":"Returned when a request is valid in form but violates a business rule of the catalog, such as an unsupported product-type change. The message describes the rule that was violated, and a stable code identifies it.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","description":"Standard error payload.","properties":{"non_field_errors":{"type":"string","description":"Human-readable error message."},"error_code":{"type":"string","description":"Machine-readable error code."}}}}}} ``` ## The ImportOptions object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ImportOptions":{"type":"object","description":"Optional import settings, sent as a JSON string in the `params` field.","properties":{"skip_post_migration":{"type":"boolean","description":"When enabled, skips the follow-up processing that normally runs after the records are imported. This matters most for `order_item` imports: the post-processing step **deletes every order whose `amount` does not equal the sum of its imported item prices** (see OrderItemImportRow). Enable this option to keep such orders untouched."},"allow_empty_phone":{"type":"boolean","description":"Applies to customer imports. When enabled, customers without a phone number are imported anyway; otherwise a phone number is required. This only applies when the phone value is `null` or the column is omitted — a present but empty phone cell (`\"\"`) is still rejected."},"default_phone":{"type":"string","description":"Applies to customer imports. Phone number to assign to customers whose record has no phone number, when empty phone numbers are not allowed. Like `allow_empty_phone`, this substitution happens only for `null` or omitted phone values, not for an empty string."}}}}}} ``` ## The UserImportRow object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"UserImportRow":{"type":"object","description":"One customer record (one row of a customer data file).","required":["customer_code","email","first_name","last_name","sms_allowed","email_allowed","date_joined","password","password_algorithm","verified"],"properties":{"customer_code":{"type":"string","description":"Unique code identifying the customer in the source system. Used to link addresses and orders to this customer."},"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"gender":{"type":["string","null"],"enum":["male","female","",null],"description":"Optional. May be left empty or omitted."},"sms_allowed":{"type":"boolean","description":"Whether the customer accepts SMS notifications. Accepts (case-insensitive) true/false, yes/no, y/n, t/f, on/off and 1/0."},"email_allowed":{"type":"boolean","description":"Whether the customer accepts email notifications. Accepts (case-insensitive) true/false, yes/no, y/n, t/f, on/off and 1/0."},"call_allowed":{"type":["boolean","null"],"description":"Optional. Whether the customer accepts phone calls."},"phone":{"type":["string","null"],"description":"Phone number. Required unless empty phone numbers are allowed or a default phone number is provided in the import options. An empty string (`\"\"`) is not accepted — omit the column or send `null` to rely on `allow_empty_phone` / `default_phone`."},"date_of_birth":{"type":["string","null"],"format":"date","description":"Optional. Accepted formats: YYYY-MM-DD, YYYY/MM/DD, DD.MM.YYYY, DD-MM-YYYY and DD/MM/YYYY."},"date_joined":{"type":"string","format":"date-time","description":"When the customer first registered. Accepted formats: `YYYY-MM-DDTHH:MM:SS.ffffffZ`, `YYYY-MM-DDTHH:MM:SSZ`, `YYYY-MM-DD HH:MM:SS.ffffff`, `YYYY-MM-DD HH:MM:SS`, `YYYY-MM-DD` and `DD.MM.YYYY HH:MM:SS`."},"facebook_uuid":{"type":["string","null"],"description":"Optional. When provided, a Facebook social-login account is created for the customer with this value as its Facebook user id, so they can keep signing in with Facebook."},"password":{"type":"string","description":"The customer's existing (hashed) password, so they can keep signing in with it."},"password_algorithm":{"type":"string","enum":["sha1","md5","sha256"],"description":"The algorithm used to hash the supplied password. Note: this is a required column but is not currently persisted or used during import — the `password` value is stored as-is."},"verified":{"type":"boolean","description":"Whether the customer's email address is already verified. Accepts (case-insensitive) true/false, yes/no, y/n, t/f, on/off and 1/0."},"attributes":{"type":"object","description":"Optional set of additional custom fields for the customer.","additionalProperties":true},"user_type":{"type":"string","enum":["guest","registered"],"default":"registered","description":"Optional. Defaults to registered."}}}}}} ``` ## The AddressImportRow object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AddressImportRow":{"type":"object","description":"One address record. Links to a customer imported earlier.","required":["customer_code","email","first_name","last_name","line","city","township","country"],"properties":{"customer_code":{"type":"string","description":"The customer code of a previously migrated customer this address belongs to."},"email":{"type":"string","format":"email"},"phone_number":{"type":["string","null"],"description":"Optional."},"first_name":{"type":"string","maxLength":255},"last_name":{"type":"string","maxLength":255},"title":{"type":["string","null"],"maxLength":128,"description":"Optional label for the address (e.g. Home, Work)."},"line":{"type":"string","maxLength":255,"description":"Street address."},"tax_office":{"type":["string","null"],"description":"Optional."},"tax_no":{"type":["string","null"],"description":"Optional."},"city":{"type":"string","description":"City name. Resolved hierarchically: the city must exist under the given `country`. A city name that does not exist within the declared country is rejected (the `city` field reports \"does not exist\"), even if a city with that name exists under a different country."},"township":{"type":"string","description":"Township name. Resolved hierarchically: it must exist under the given `city` (and `country`). A township that does not exist under the declared city is rejected on the `township` field."},"district":{"type":["string","null"],"description":"Optional district name. Must belong to the given township."},"country":{"type":"string","description":"Country name. Matched by name against existing countries. Acts as the top of the country → city → township hierarchy: `city` and `township` are resolved within this country."},"company_name":{"type":["string","null"],"description":"Optional."},"extra_field":{"type":["object","null"],"description":"Optional additional address data. When sending XLS/CSV, provide a valid JSON string in the cell. When sending a JSON file, provide a JSON object."}}}}}} ``` ## The OrderImportRow object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"OrderImportRow":{"type":"object","description":"One historical order. Links to a customer imported earlier. Columns marked required must be present in the file; some of them may be left empty.\n\n**Warning — order/item reconciliation:** after a subsequent `order_item` import, any order whose `amount` does not exactly equal the sum of its imported item prices is **deleted** (unless `skip_post_migration` is set). The sum does **not** multiply by item `quantity`, so `amount` must equal the plain sum of the `price` values of its items. See OrderItemImportRow.","required":["number","customer_code","user_email","status","created_date","amount","currency","payment_type","bank","tracking_number","shipping_company","shipping_address","billing_address"],"properties":{"number":{"type":"string","maxLength":128,"description":"Unique order number in the source system. Used to link order items to this order."},"customer_code":{"type":"string","description":"The customer code of a previously migrated customer who placed the order."},"user_email":{"type":"string","format":"email"},"status":{"type":"string","maxLength":64},"created_date":{"type":"string","format":"date-time","description":"When the order was created. Accepted formats: `YYYY-MM-DDTHH:MM:SS.ffffffZ`, `YYYY-MM-DDTHH:MM:SSZ`, `YYYY-MM-DD HH:MM:SS.ffffff`, `YYYY-MM-DD HH:MM:SS`, `YYYY-MM-DD` and `DD.MM.YYYY HH:MM:SS`."},"amount":{"type":"string","description":"Total order amount. Decimal with at most 12 total digits and 2 decimal places (i.e. up to 10 digits before the decimal point); values outside this range are rejected."},"discount_amount":{"type":["string","null"],"description":"Optional. Total discount applied to the order. Same numeric limits as `amount` (up to 12 total digits, 2 decimal places)."},"currency":{"type":"string","description":"ISO currency code.","enum":["try","eur","usd","egp","gbp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd","amd","cfa","lyd"]},"payment_type":{"type":["string","null"],"maxLength":64},"bank":{"type":["string","null"],"maxLength":64},"installment_count":{"type":"integer","minimum":1,"description":"Optional."},"tracking_number":{"type":["string","null"],"maxLength":64},"shipping_company":{"type":["string","null"],"description":"Shipping carrier the order was sent with.","enum":["aras","ups","asil","yurtici","mng","hbexpress","aramex","other","ismail","gls","hoopkapida","fancourier","tmmexpress","ptt","horoz","novaposhta","droplight","surat","ups_intl","b2c_direct","jetizz","tyexpress","ay_cargo","cainiao","acs","packupp","k_gelsin","birgunde","kargo_ist","giz","mylerz","mylerzsdd","r2s","boomex","chrono","scotty","netkargo","murat_lgc","fast_cargo","dpd","in_post","k_sende","rupost","cdek","loomis","carrtell","speeta","bringo","dhlexpress","bovo","gelal","arvato","bpost_athome","bpost_24_7","cathedis","dincer","sameday","gkn","svuum","hjetxl","aramex_express","tnt_cargo","ceva_cargo","bringo_express","sendeo","cargus","pinkpost","speedy","deliverigo","jetizz_v7","evdemo_lojistik","extension","apiship","octovan_express","clickpost","iMile","jetlogi","bolt","pony_express","boxaty","monist","city_express","fero_ai","carriyo","pakettaxi","falcon_flex","porter_express","sky_express","pts_express","bpost_pickup","shipx","fareye","bpost_international",null]},"shipping_address":{"type":"string","maxLength":512,"description":"The shipping address as text."},"billing_address":{"type":"string","maxLength":512,"description":"The billing address as text."},"extra_field":{"type":"object","description":"Optional additional order data.","additionalProperties":true}}}}}} ``` ## The OrderItemImportRow object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"OrderItemImportRow":{"type":"object","description":"One line item of a migrated order. Columns marked required must be present in the file; some of them may be left empty.\n\n**Warning — destructive post-processing:** once an `order_item` import finishes, every order whose `amount` does not exactly equal the sum of its imported item prices is **deleted**. The reconciliation sums the item `price` values **without** multiplying by `quantity`, so an order with a correctly-priced multi-quantity item can be removed if its `amount` reflects `price × quantity`. Set `skip_post_migration: true` in the import options to disable this deletion. Orders that received no items are not affected.","required":["order_number","product","sku","quantity","price","image_url"],"properties":{"order_number":{"type":"string","description":"The order number of a previously migrated order this item belongs to."},"product":{"type":["string","null"],"maxLength":256,"description":"Product name."},"sku":{"type":["string","null"],"maxLength":128,"description":"Stock keeping unit of the purchased item."},"quantity":{"type":["integer","null"],"minimum":1},"price":{"type":"string","description":"Unit price. Decimal with at most 12 total digits and 2 decimal places; values outside this range are rejected."},"image_url":{"type":["string","null"],"format":"uri"},"extra_field":{"type":"object","description":"Optional additional line-item data. Stored as a JSON field, so it accepts any JSON value (object, array or scalar), not only an object.","additionalProperties":true}}}}}} ``` ## The RetailStoreImportRow object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"RetailStoreImportRow":{"type":"object","description":"One physical store record. Columns marked required must be present in the file; some of them may be left empty.","required":["name","city","township","address","phone_number","fax_phone_number","latitude","longitude"],"properties":{"name":{"type":"string","maxLength":255},"city":{"type":"string","description":"City name. Used only to validate that the given `township` belongs to it — it is **not stored** on the retail store record itself (the store keeps only the township). Required."},"township":{"type":"string","description":"Township name. Must belong to the given city."},"address":{"type":"string","description":"Full store address."},"phone_number":{"type":"string","maxLength":128},"fax_phone_number":{"type":["string","null"],"maxLength":128,"description":"Required column, but the value may be left empty (sent as `null`)."},"store_hours":{"type":"string","description":"Optional. Opening hours for the seven days of the week as a comma-separated list of \"open-close\" ranges; leave a day empty to mark it closed."},"latitude":{"type":"string","description":"Store latitude. Decimal with at most 11 total digits and 8 decimal places; more than 8 decimal places is rejected."},"longitude":{"type":"string","description":"Store longitude. Decimal with at most 11 total digits and 8 decimal places; more than 8 decimal places is rejected."}}}}}} ``` ## The AttributeDataType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeDataType":{"type":"string","description":"The data type of an attribute, controlling how its value is entered and interpreted. See the **Data Types** table under **Attributes**.","enum":["text","email","area","date","datetime","bool","valuelabel","dropdown","multiple","price","nested","image","file","model","bundle"]}}}} ``` ## The AttributeSetType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeSetType":{"type":"string","description":"The type of an attribute set.\n* `simple` — a standard attribute set (default)\n* `grouped` — an attribute set used for grouped products","enum":["simple","grouped"]}}}} ``` ## The Attribute object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"Attribute":{"type":"object","description":"An attribute definition as returned by the API.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute.","readOnly":true},"key":{"type":"string","maxLength":255,"description":"The unique machine key of the attribute. Matches `^[a-zA-Z_][a-zA-Z0-9_-]*$`."},"name":{"type":"string","maxLength":255,"description":"The human-readable, translatable name of the attribute."},"data_type":{"$ref":"#/components/schemas/AttributeDataType"},"default_value":{"type":["integer","null"],"description":"The identifier of the attribute value used as the default, when any."},"is_required":{"type":"boolean","description":"Whether the attribute must have a value on the product."},"is_visible":{"type":"boolean","description":"Whether the attribute is shown in management and storefront contexts."},"is_searchable":{"type":"boolean","description":"Whether the attribute is indexed for search."},"is_filterable":{"type":"boolean","description":"Whether the attribute can be used as a storefront filter."},"is_variant":{"type":"boolean","description":"Whether the attribute distinguishes variants of a product."},"is_variant_listable":{"type":"boolean","description":"Whether the attribute participates in choosing the listable variant."},"is_form_required":{"type":"boolean","description":"Whether the attribute is required in the product form."},"is_form_field_required":{"type":"boolean","description":"Whether the attribute's form field is required."}}},"AttributeDataType":{"type":"string","description":"The data type of an attribute, controlling how its value is entered and interpreted. See the **Data Types** table under **Attributes**.","enum":["text","email","area","date","datetime","bool","valuelabel","dropdown","multiple","price","nested","image","file","model","bundle"]}}}} ``` ## The AttributeRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeRequest":{"type":"object","description":"The payload accepted when creating or fully updating an attribute.","required":["key","name","data_type"],"properties":{"key":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z_][a-zA-Z0-9_-]*$","description":"The unique machine key of the attribute."},"name":{"type":"string","maxLength":255,"description":"The human-readable, translatable name of the attribute."},"data_type":{"$ref":"#/components/schemas/AttributeDataType"},"default_value":{"type":["integer","null"],"description":"The identifier of the attribute value used as the default, when any."},"is_required":{"type":"boolean","description":"Whether the attribute must have a value on the product."},"is_visible":{"type":"boolean","description":"Whether the attribute is shown in management and storefront contexts."},"is_searchable":{"type":"boolean","description":"Whether the attribute is indexed for search."},"is_filterable":{"type":"boolean","description":"Whether the attribute can be used as a storefront filter."},"is_variant":{"type":"boolean","description":"Whether the attribute distinguishes variants of a product."},"is_variant_listable":{"type":"boolean","description":"Whether the attribute participates in choosing the listable variant."},"is_form_required":{"type":"boolean","description":"Whether the attribute is required in the product form."},"is_form_field_required":{"type":"boolean","description":"Whether the attribute's form field is required."},"translations":{"type":["object","null"],"writeOnly":true,"description":"Localized values of the translatable fields, keyed by language code. Write-only.","additionalProperties":true}}},"AttributeDataType":{"type":"string","description":"The data type of an attribute, controlling how its value is entered and interpreted. See the **Data Types** table under **Attributes**.","enum":["text","email","area","date","datetime","bool","valuelabel","dropdown","multiple","price","nested","image","file","model","bundle"]}}}} ``` ## The AttributePatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributePatchRequest":{"type":"object","description":"The payload accepted when partially updating an attribute. All fields are optional; only the fields you send are changed.","properties":{"key":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z_][a-zA-Z0-9_-]*$","description":"The unique machine key of the attribute."},"name":{"type":"string","maxLength":255,"description":"The human-readable, translatable name of the attribute."},"data_type":{"$ref":"#/components/schemas/AttributeDataType"},"default_value":{"type":["integer","null"],"description":"The identifier of the attribute value used as the default, when any."},"is_required":{"type":"boolean"},"is_visible":{"type":"boolean"},"is_searchable":{"type":"boolean"},"is_filterable":{"type":"boolean"},"is_variant":{"type":"boolean"},"is_variant_listable":{"type":"boolean"},"is_form_required":{"type":"boolean"},"is_form_field_required":{"type":"boolean"},"translations":{"type":["object","null"],"writeOnly":true,"description":"Localized values of the translatable fields, keyed by language code. Write-only.","additionalProperties":true}}},"AttributeDataType":{"type":"string","description":"The data type of an attribute, controlling how its value is entered and interpreted. See the **Data Types** table under **Attributes**.","enum":["text","email","area","date","datetime","bool","valuelabel","dropdown","multiple","price","nested","image","file","model","bundle"]}}}} ``` ## The PaginatedAttributeList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedAttributeList":{"type":"object","description":"A page of attribute results.","properties":{"count":{"type":"integer","description":"The total number of attributes matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The attributes on the current page.","items":{"$ref":"#/components/schemas/Attribute"}}}},"Attribute":{"type":"object","description":"An attribute definition as returned by the API.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute.","readOnly":true},"key":{"type":"string","maxLength":255,"description":"The unique machine key of the attribute. Matches `^[a-zA-Z_][a-zA-Z0-9_-]*$`."},"name":{"type":"string","maxLength":255,"description":"The human-readable, translatable name of the attribute."},"data_type":{"$ref":"#/components/schemas/AttributeDataType"},"default_value":{"type":["integer","null"],"description":"The identifier of the attribute value used as the default, when any."},"is_required":{"type":"boolean","description":"Whether the attribute must have a value on the product."},"is_visible":{"type":"boolean","description":"Whether the attribute is shown in management and storefront contexts."},"is_searchable":{"type":"boolean","description":"Whether the attribute is indexed for search."},"is_filterable":{"type":"boolean","description":"Whether the attribute can be used as a storefront filter."},"is_variant":{"type":"boolean","description":"Whether the attribute distinguishes variants of a product."},"is_variant_listable":{"type":"boolean","description":"Whether the attribute participates in choosing the listable variant."},"is_form_required":{"type":"boolean","description":"Whether the attribute is required in the product form."},"is_form_field_required":{"type":"boolean","description":"Whether the attribute's form field is required."}}},"AttributeDataType":{"type":"string","description":"The data type of an attribute, controlling how its value is entered and interpreted. See the **Data Types** table under **Attributes**.","enum":["text","email","area","date","datetime","bool","valuelabel","dropdown","multiple","price","nested","image","file","model","bundle"]}}}} ``` ## The AttributeValue object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeValue":{"type":"object","description":"A predefined value of an attribute as returned by the API.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute value.","readOnly":true},"attribute":{"type":"integer","description":"The identifier of the parent attribute."},"value":{"type":"string","description":"The value."},"order":{"type":["integer","null"],"description":"The sort order of the value. Values are listed by `order`, then `value`."},"label":{"type":["string","null"],"description":"The translatable display label of the value, when any."}}}}}} ``` ## The AttributeValueRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeValueRequest":{"type":"object","description":"The payload accepted when creating or fully updating an attribute value.","required":["attribute","value"],"properties":{"attribute":{"type":"integer","description":"The identifier of the parent attribute. Together with `value`, must be unique."},"value":{"type":"string","description":"The value. Together with `attribute`, must be unique."},"order":{"type":["integer","null"],"description":"The sort order of the value. When omitted, the server tries to derive it from the numeric interpretation of `value`."},"label":{"type":["string","null"],"description":"The translatable display label of the value."},"translations":{"type":["object","null"],"writeOnly":true,"description":"Localized values of the translatable fields, keyed by language code. Write-only.","additionalProperties":true}}}}}} ``` ## The AttributeValuePatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeValuePatchRequest":{"type":"object","description":"The payload accepted when partially updating an attribute value. All fields are optional; only the fields you send are changed.","properties":{"attribute":{"type":"integer","description":"The identifier of the parent attribute."},"value":{"type":"string","description":"The value."},"order":{"type":["integer","null"],"description":"The sort order of the value."},"label":{"type":["string","null"],"description":"The translatable display label of the value."},"translations":{"type":["object","null"],"writeOnly":true,"description":"Localized values of the translatable fields, keyed by language code. Write-only.","additionalProperties":true}}}}}} ``` ## The PaginatedAttributeValueList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedAttributeValueList":{"type":"object","description":"A page of attribute value results.","properties":{"count":{"type":"integer","description":"The total number of attribute values matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The attribute values on the current page.","items":{"$ref":"#/components/schemas/AttributeValue"}}}},"AttributeValue":{"type":"object","description":"A predefined value of an attribute as returned by the API.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute value.","readOnly":true},"attribute":{"type":"integer","description":"The identifier of the parent attribute."},"value":{"type":"string","description":"The value."},"order":{"type":["integer","null"],"description":"The sort order of the value. Values are listed by `order`, then `value`."},"label":{"type":["string","null"],"description":"The translatable display label of the value, when any."}}}}}} ``` ## The AttributeConfig object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeConfig":{"type":"object","description":"The membership of one attribute in one attribute set. Each behavior flag is nullable; a `null` value means the flag is inherited from the parent attribute, and the read-only `default_fields` array reports which flags are currently inherited.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute configuration.","readOnly":true},"attribute":{"type":"integer","description":"The identifier of the attribute."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set."},"is_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_required`; `null` inherits it."},"is_visible":{"type":["boolean","null"],"description":"Overrides the attribute's `is_visible`; `null` inherits it."},"is_searchable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_searchable`; `null` inherits it."},"is_filterable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_filterable`; `null` inherits it."},"is_variant":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant`; `null` inherits it."},"is_variant_listable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant_listable`; `null` inherits it. Changing this recomputes the listable status of the attribute set's products."},"is_form_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_required`; `null` inherits it."},"is_form_field_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_field_required`; `null` inherits it."},"default_fields":{"type":"array","readOnly":true,"description":"The names of the behavior flags currently inherited from the attribute (those left `null`).","items":{"type":"string"}},"order":{"type":["integer","null"],"description":"The sort order of the attribute within the set."},"attribute_config_group":{"type":["integer","null"],"description":"The identifier of the attribute configuration group this configuration belongs to, when any."}}}}}} ``` ## The AttributeConfigRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeConfigRequest":{"type":"object","description":"The payload accepted when creating or fully updating an attribute configuration. On update, `attribute` and `attribute_set` are immutable and any values sent for them are ignored.","required":["attribute","attribute_set"],"properties":{"attribute":{"type":"integer","description":"The identifier of the attribute. Together with `attribute_set`, must be unique."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set. Together with `attribute`, must be unique."},"is_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_required`; `null` inherits it."},"is_visible":{"type":["boolean","null"],"description":"Overrides the attribute's `is_visible`; `null` inherits it."},"is_searchable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_searchable`; `null` inherits it."},"is_filterable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_filterable`; `null` inherits it."},"is_variant":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant`; `null` inherits it."},"is_variant_listable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant_listable`; `null` inherits it."},"is_form_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_required`; `null` inherits it."},"is_form_field_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_field_required`; `null` inherits it."},"order":{"type":["integer","null"],"description":"The sort order of the attribute within the set."},"attribute_config_group":{"type":["integer","null"],"description":"The identifier of the attribute configuration group this configuration belongs to."}}}}}} ``` ## The AttributeConfigPatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeConfigPatchRequest":{"type":"object","description":"The payload accepted when partially updating an attribute configuration. All fields are optional; only the fields you send are changed. `attribute` and `attribute_set` are immutable and any values sent for them are ignored.","properties":{"is_required":{"type":["boolean","null"]},"is_visible":{"type":["boolean","null"]},"is_searchable":{"type":["boolean","null"]},"is_filterable":{"type":["boolean","null"]},"is_variant":{"type":["boolean","null"]},"is_variant_listable":{"type":["boolean","null"],"description":"Changing this recomputes the listable status of the attribute set's products."},"is_form_required":{"type":["boolean","null"]},"is_form_field_required":{"type":["boolean","null"]},"order":{"type":["integer","null"]},"attribute_config_group":{"type":["integer","null"]}}}}}} ``` ## The PaginatedAttributeConfigList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedAttributeConfigList":{"type":"object","description":"A page of attribute configuration results.","properties":{"count":{"type":"integer","description":"The total number of attribute configurations matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The attribute configurations on the current page.","items":{"$ref":"#/components/schemas/AttributeConfig"}}}},"AttributeConfig":{"type":"object","description":"The membership of one attribute in one attribute set. Each behavior flag is nullable; a `null` value means the flag is inherited from the parent attribute, and the read-only `default_fields` array reports which flags are currently inherited.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute configuration.","readOnly":true},"attribute":{"type":"integer","description":"The identifier of the attribute."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set."},"is_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_required`; `null` inherits it."},"is_visible":{"type":["boolean","null"],"description":"Overrides the attribute's `is_visible`; `null` inherits it."},"is_searchable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_searchable`; `null` inherits it."},"is_filterable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_filterable`; `null` inherits it."},"is_variant":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant`; `null` inherits it."},"is_variant_listable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant_listable`; `null` inherits it. Changing this recomputes the listable status of the attribute set's products."},"is_form_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_required`; `null` inherits it."},"is_form_field_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_field_required`; `null` inherits it."},"default_fields":{"type":"array","readOnly":true,"description":"The names of the behavior flags currently inherited from the attribute (those left `null`).","items":{"type":"string"}},"order":{"type":["integer","null"],"description":"The sort order of the attribute within the set."},"attribute_config_group":{"type":["integer","null"],"description":"The identifier of the attribute configuration group this configuration belongs to, when any."}}}}}} ``` ## The AttributeSet object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeSet":{"type":"object","description":"A named group of attribute configurations assigned to products.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute set.","readOnly":true},"name":{"type":"string","maxLength":255,"description":"The unique name of the attribute set."},"attribute_set_type":{"$ref":"#/components/schemas/AttributeSetType"},"attributeconfig_set":{"type":"array","readOnly":true,"description":"The attribute configurations belonging to this set. Managed with the **Attribute Configurations** endpoints.","items":{"$ref":"#/components/schemas/AttributeConfig"}}}},"AttributeSetType":{"type":"string","description":"The type of an attribute set.\n* `simple` — a standard attribute set (default)\n* `grouped` — an attribute set used for grouped products","enum":["simple","grouped"]},"AttributeConfig":{"type":"object","description":"The membership of one attribute in one attribute set. Each behavior flag is nullable; a `null` value means the flag is inherited from the parent attribute, and the read-only `default_fields` array reports which flags are currently inherited.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute configuration.","readOnly":true},"attribute":{"type":"integer","description":"The identifier of the attribute."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set."},"is_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_required`; `null` inherits it."},"is_visible":{"type":["boolean","null"],"description":"Overrides the attribute's `is_visible`; `null` inherits it."},"is_searchable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_searchable`; `null` inherits it."},"is_filterable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_filterable`; `null` inherits it."},"is_variant":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant`; `null` inherits it."},"is_variant_listable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant_listable`; `null` inherits it. Changing this recomputes the listable status of the attribute set's products."},"is_form_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_required`; `null` inherits it."},"is_form_field_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_field_required`; `null` inherits it."},"default_fields":{"type":"array","readOnly":true,"description":"The names of the behavior flags currently inherited from the attribute (those left `null`).","items":{"type":"string"}},"order":{"type":["integer","null"],"description":"The sort order of the attribute within the set."},"attribute_config_group":{"type":["integer","null"],"description":"The identifier of the attribute configuration group this configuration belongs to, when any."}}}}}} ``` ## The AttributeSetRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeSetRequest":{"type":"object","description":"The payload accepted when creating or fully updating an attribute set.","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"description":"The unique name of the attribute set."},"attribute_set_type":{"$ref":"#/components/schemas/AttributeSetType"}}},"AttributeSetType":{"type":"string","description":"The type of an attribute set.\n* `simple` — a standard attribute set (default)\n* `grouped` — an attribute set used for grouped products","enum":["simple","grouped"]}}}} ``` ## The AttributeSetPatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeSetPatchRequest":{"type":"object","description":"The payload accepted when partially updating an attribute set. All fields are optional; only the fields you send are changed.","properties":{"name":{"type":"string","maxLength":255,"description":"The unique name of the attribute set."},"attribute_set_type":{"$ref":"#/components/schemas/AttributeSetType"}}},"AttributeSetType":{"type":"string","description":"The type of an attribute set.\n* `simple` — a standard attribute set (default)\n* `grouped` — an attribute set used for grouped products","enum":["simple","grouped"]}}}} ``` ## The PaginatedAttributeSetList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedAttributeSetList":{"type":"object","description":"A page of attribute set results.","properties":{"count":{"type":"integer","description":"The total number of attribute sets matching the query."},"next":{"type":["string","null"],"format":"uri","description":"The URL of the next page of results, when available."},"previous":{"type":["string","null"],"format":"uri","description":"The URL of the previous page of results, when available."},"results":{"type":"array","description":"The attribute sets on the current page.","items":{"$ref":"#/components/schemas/AttributeSet"}}}},"AttributeSet":{"type":"object","description":"A named group of attribute configurations assigned to products.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute set.","readOnly":true},"name":{"type":"string","maxLength":255,"description":"The unique name of the attribute set."},"attribute_set_type":{"$ref":"#/components/schemas/AttributeSetType"},"attributeconfig_set":{"type":"array","readOnly":true,"description":"The attribute configurations belonging to this set. Managed with the **Attribute Configurations** endpoints.","items":{"$ref":"#/components/schemas/AttributeConfig"}}}},"AttributeSetType":{"type":"string","description":"The type of an attribute set.\n* `simple` — a standard attribute set (default)\n* `grouped` — an attribute set used for grouped products","enum":["simple","grouped"]},"AttributeConfig":{"type":"object","description":"The membership of one attribute in one attribute set. Each behavior flag is nullable; a `null` value means the flag is inherited from the parent attribute, and the read-only `default_fields` array reports which flags are currently inherited.","properties":{"pk":{"type":"integer","description":"The unique identifier of the attribute configuration.","readOnly":true},"attribute":{"type":"integer","description":"The identifier of the attribute."},"attribute_set":{"type":"integer","description":"The identifier of the attribute set."},"is_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_required`; `null` inherits it."},"is_visible":{"type":["boolean","null"],"description":"Overrides the attribute's `is_visible`; `null` inherits it."},"is_searchable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_searchable`; `null` inherits it."},"is_filterable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_filterable`; `null` inherits it."},"is_variant":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant`; `null` inherits it."},"is_variant_listable":{"type":["boolean","null"],"description":"Overrides the attribute's `is_variant_listable`; `null` inherits it. Changing this recomputes the listable status of the attribute set's products."},"is_form_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_required`; `null` inherits it."},"is_form_field_required":{"type":["boolean","null"],"description":"Overrides the attribute's `is_form_field_required`; `null` inherits it."},"default_fields":{"type":"array","readOnly":true,"description":"The names of the behavior flags currently inherited from the attribute (those left `null`).","items":{"type":"string"}},"order":{"type":["integer","null"],"description":"The sort order of the attribute within the set."},"attribute_config_group":{"type":["integer","null"],"description":"The identifier of the attribute configuration group this configuration belongs to, when any."}}}}}} ``` ## The AttributeConfigGroup object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeConfigGroup":{"type":"object","description":"An attribute config group record.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the attribute config group."},"name":{"type":"string","maxLength":255,"description":"Unique display name of the group."},"order":{"type":"integer","minimum":0,"description":"Sort order used when listing groups. Lower values appear first.","default":0}},"required":["pk","name","order"]}}}} ``` ## The AttributeConfigGroupRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeConfigGroupRequest":{"type":"object","description":"Fields for creating or fully replacing an attribute config group.","required":["name"],"properties":{"name":{"type":"string","maxLength":255,"description":"Unique display name of the group. Must be unique across all attribute config groups."},"order":{"type":"integer","minimum":0,"description":"Sort order. Lower values appear first. Defaults to `0` when omitted.","default":0}}}}}} ``` ## The AttributeConfigGroupPatchRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"AttributeConfigGroupPatchRequest":{"type":"object","description":"Fields for partially updating an attribute config group. All fields are optional.","properties":{"name":{"type":"string","maxLength":255,"description":"Unique display name of the group. Must be unique across all attribute config groups."},"order":{"type":"integer","minimum":0,"description":"Sort order. Lower values appear first."}}}}}} ``` ## The PaginatedAttributeConfigGroupList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedAttributeConfigGroupList":{"type":"object","description":"A paginated list of attribute config groups.","properties":{"count":{"type":"integer","description":"Total number of attribute config groups."},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or `null` if this is the last page."},"previous":{"type":["string","null"],"format":"uri","description":"URL of the previous page, or `null` if this is the first page."},"results":{"type":"array","description":"The attribute config groups on the current page.","items":{"$ref":"#/components/schemas/AttributeConfigGroup"}}}},"AttributeConfigGroup":{"type":"object","description":"An attribute config group record.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the attribute config group."},"name":{"type":"string","maxLength":255,"description":"Unique display name of the group."},"order":{"type":"integer","minimum":0,"description":"Sort order used when listing groups. Lower values appear first.","default":0}},"required":["pk","name","order"]}}}} ``` ## The ShippingOptionDeliveryType object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ShippingOptionDeliveryType":{"type":"string","description":"Delivery type of the shipping option.\n\n| Value | Description |\n|---|---|\n| `standard` | Standard delivery |\n| `same_day` | Same-day delivery |\n| `next_day` | Next-day delivery |\n| `cargo` | Cargo delivery |\n| `cargo_with_appointment` | Cargo delivery with scheduled appointment |\n| `store_pickup` | Click & collect from retail store |\n| `digital` | Digital / downloadable product delivery |","enum":["standard","same_day","next_day","cargo","cargo_with_appointment","store_pickup","digital"]}}}} ``` ## The ShippingOptionDeliveryTypeDetail object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ShippingOptionDeliveryTypeDetail":{"type":"object","description":"Read representation of a delivery type — includes the raw enum value and its human-readable label.","properties":{"value":{"type":"string","description":"Enum value."},"label":{"type":"string","description":"Human-readable label for the delivery type."}}}}}} ``` ## The ShippingOptionKwargs object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}}}}} ``` ## The ShippingOption object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ShippingOption":{"type":"object","description":"A shipping option returned by the API.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the shipping option."},"name":{"type":"string","description":"Display name. Returned in the active request language, falling back to the default language."},"slug":{"type":"string","description":"URL-friendly unique identifier."},"is_active":{"type":"boolean","description":"Whether the shipping option is active. Inactive options are hidden from the storefront.","default":true},"calculator":{"type":"object","description":"Calculator configuration. Determines how the shipping cost is computed.\n\nThe object must contain at minimum a `slug` key identifying the calculator. See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available calculators and their parameters."},"rule":{"type":"object","description":"Rule configuration. Determines which baskets are eligible for this shipping option.\n\nThe object must contain a `slug` key identifying the rule. The `name` key is optional. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order used when listing options. Lower values appear first.","default":0},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryTypeDetail"},{"type":"null"}],"description":"Delivery type of the shipping option."}},"required":["pk","name","slug","is_active","calculator","rule","sort_order"]},"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}},"ShippingOptionDeliveryTypeDetail":{"type":"object","description":"Read representation of a delivery type — includes the raw enum value and its human-readable label.","properties":{"value":{"type":"string","description":"Enum value."},"label":{"type":"string","description":"Human-readable label for the delivery type."}}}}}} ``` ## The ShippingOptionRequest object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ShippingOptionRequest":{"type":"object","description":"Fields for creating or updating a shipping option.","properties":{"name":{"type":"string","description":"Display name of the shipping option."},"slug":{"type":"string","description":"URL-friendly unique identifier. Must be unique across all shipping options."},"is_active":{"type":"boolean","description":"Whether the shipping option is active.","default":true},"calculator":{"type":"object","description":"Calculator configuration. The object must contain a `slug` key identifying the calculator. See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available calculators and their parameters."},"rule":{"type":"object","description":"Rule configuration. The object must contain a `slug` key identifying the rule. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order. Lower values appear first.","default":0},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryType"},{"type":"null"}],"description":"Delivery type of the shipping option."}},"required":["name","slug","calculator","rule"]},"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}},"ShippingOptionDeliveryType":{"type":"string","description":"Delivery type of the shipping option.\n\n| Value | Description |\n|---|---|\n| `standard` | Standard delivery |\n| `same_day` | Same-day delivery |\n| `next_day` | Next-day delivery |\n| `cargo` | Cargo delivery |\n| `cargo_with_appointment` | Cargo delivery with scheduled appointment |\n| `store_pickup` | Click & collect from retail store |\n| `digital` | Digital / downloadable product delivery |","enum":["standard","same_day","next_day","cargo","cargo_with_appointment","store_pickup","digital"]}}}} ``` ## The PaginatedShippingOptionList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedShippingOptionList":{"type":"object","description":"A paginated list of shipping options.","properties":{"count":{"type":"integer","description":"Total number of shipping options."},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or `null` if this is the last page."},"previous":{"type":["string","null"],"format":"uri","description":"URL of the previous page, or `null` if this is the first page."},"results":{"type":"array","description":"The shipping options on the current page.","items":{"$ref":"#/components/schemas/ShippingOption"}}}},"ShippingOption":{"type":"object","description":"A shipping option returned by the API.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the shipping option."},"name":{"type":"string","description":"Display name. Returned in the active request language, falling back to the default language."},"slug":{"type":"string","description":"URL-friendly unique identifier."},"is_active":{"type":"boolean","description":"Whether the shipping option is active. Inactive options are hidden from the storefront.","default":true},"calculator":{"type":"object","description":"Calculator configuration. Determines how the shipping cost is computed.\n\nThe object must contain at minimum a `slug` key identifying the calculator. See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available calculators and their parameters."},"rule":{"type":"object","description":"Rule configuration. Determines which baskets are eligible for this shipping option.\n\nThe object must contain a `slug` key identifying the rule. The `name` key is optional. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order used when listing options. Lower values appear first.","default":0},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryTypeDetail"},{"type":"null"}],"description":"Delivery type of the shipping option."}},"required":["pk","name","slug","is_active","calculator","rule","sort_order"]},"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}},"ShippingOptionDeliveryTypeDetail":{"type":"object","description":"Read representation of a delivery type — includes the raw enum value and its human-readable label.","properties":{"value":{"type":"string","description":"Enum value."},"label":{"type":"string","description":"Human-readable label for the delivery type."}}}}}} ``` ## The ShippingOptionGroup object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"ShippingOptionGroup":{"type":"object","description":"A shipping option group — the shipping cost line item attached to an order. Groups are created internally by the order pipeline when an order is placed, pairing the `shipping_option` that was selected with the final `amount` charged and the order items it covers. This resource is read-only; it cannot be created, updated, or deleted through this API.","properties":{"pk":{"type":"integer","description":"Unique identifier of the shipping option group."},"amount":{"type":"string","description":"Shipping cost charged for this group. Decimal with at most 12 total digits and 2 decimal places (i.e. up to 10 digits before the decimal point). Resolved by the shipping option's calculator at the time the order was placed; see the **Dynamic Settings & Environment Variables** section for the settings that influence how it was computed."},"created_date":{"type":"string","format":"date-time","description":"When the group was created."},"modified_date":{"type":"string","format":"date-time","description":"When the group was last modified."},"shipping_option":{"allOf":[{"$ref":"#/components/schemas/ShippingOption"}],"description":"The shipping option that was selected for this group."},"order_items":{"type":"array","description":"Identifiers of the order items covered by this shipping option group.","items":{"type":"integer"}}},"required":["pk","amount","created_date","modified_date","shipping_option","order_items"]},"ShippingOption":{"type":"object","description":"A shipping option returned by the API.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the shipping option."},"name":{"type":"string","description":"Display name. Returned in the active request language, falling back to the default language."},"slug":{"type":"string","description":"URL-friendly unique identifier."},"is_active":{"type":"boolean","description":"Whether the shipping option is active. Inactive options are hidden from the storefront.","default":true},"calculator":{"type":"object","description":"Calculator configuration. Determines how the shipping cost is computed.\n\nThe object must contain at minimum a `slug` key identifying the calculator. See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available calculators and their parameters."},"rule":{"type":"object","description":"Rule configuration. Determines which baskets are eligible for this shipping option.\n\nThe object must contain a `slug` key identifying the rule. The `name` key is optional. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order used when listing options. Lower values appear first.","default":0},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryTypeDetail"},{"type":"null"}],"description":"Delivery type of the shipping option."}},"required":["pk","name","slug","is_active","calculator","rule","sort_order"]},"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}},"ShippingOptionDeliveryTypeDetail":{"type":"object","description":"Read representation of a delivery type — includes the raw enum value and its human-readable label.","properties":{"value":{"type":"string","description":"Enum value."},"label":{"type":"string","description":"Human-readable label for the delivery type."}}}}}} ``` ## The PaginatedShippingOptionGroupList object ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"components":{"schemas":{"PaginatedShippingOptionGroupList":{"type":"object","description":"A paginated list of shipping option groups.","properties":{"count":{"type":"integer","description":"Total number of shipping option groups."},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or `null` if this is the last page."},"previous":{"type":["string","null"],"format":"uri","description":"URL of the previous page, or `null` if this is the first page."},"results":{"type":"array","description":"The shipping option groups on the current page.","items":{"$ref":"#/components/schemas/ShippingOptionGroup"}}}},"ShippingOptionGroup":{"type":"object","description":"A shipping option group — the shipping cost line item attached to an order. Groups are created internally by the order pipeline when an order is placed, pairing the `shipping_option` that was selected with the final `amount` charged and the order items it covers. This resource is read-only; it cannot be created, updated, or deleted through this API.","properties":{"pk":{"type":"integer","description":"Unique identifier of the shipping option group."},"amount":{"type":"string","description":"Shipping cost charged for this group. Decimal with at most 12 total digits and 2 decimal places (i.e. up to 10 digits before the decimal point). Resolved by the shipping option's calculator at the time the order was placed; see the **Dynamic Settings & Environment Variables** section for the settings that influence how it was computed."},"created_date":{"type":"string","format":"date-time","description":"When the group was created."},"modified_date":{"type":"string","format":"date-time","description":"When the group was last modified."},"shipping_option":{"allOf":[{"$ref":"#/components/schemas/ShippingOption"}],"description":"The shipping option that was selected for this group."},"order_items":{"type":"array","description":"Identifiers of the order items covered by this shipping option group.","items":{"type":"integer"}}},"required":["pk","amount","created_date","modified_date","shipping_option","order_items"]},"ShippingOption":{"type":"object","description":"A shipping option returned by the API.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the shipping option."},"name":{"type":"string","description":"Display name. Returned in the active request language, falling back to the default language."},"slug":{"type":"string","description":"URL-friendly unique identifier."},"is_active":{"type":"boolean","description":"Whether the shipping option is active. Inactive options are hidden from the storefront.","default":true},"calculator":{"type":"object","description":"Calculator configuration. Determines how the shipping cost is computed.\n\nThe object must contain at minimum a `slug` key identifying the calculator. See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available calculators and their parameters."},"rule":{"type":"object","description":"Rule configuration. Determines which baskets are eligible for this shipping option.\n\nThe object must contain a `slug` key identifying the rule. The `name` key is optional. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order used when listing options. Lower values appear first.","default":0},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryTypeDetail"},{"type":"null"}],"description":"Delivery type of the shipping option."}},"required":["pk","name","slug","is_active","calculator","rule","sort_order"]},"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}},"ShippingOptionDeliveryTypeDetail":{"type":"object","description":"Read representation of a delivery type — includes the raw enum value and its human-readable label.","properties":{"value":{"type":"string","description":"Enum value."},"label":{"type":"string","description":"Human-readable label for the delivery type."}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/admin/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.