{ "openapi": "3.1.0", "info": { "title": "xforge Storefront API", "version": "1.0.0", "description": "Customer-facing API. Same envelope and cursor pagination as the tenant API. Tokens are customer tokens (`typ: customer`), separate from staff tokens; operations that do not require a customer token also work anonymously, and see the customer when one is sent." }, "paths": { "/api/v1/storefront/auth/account/delete": { "post": { "operationId": "storefrontDeleteAccount", "summary": "Delete a customer account with the token from the email", "description": "Final: personal details are erased (the record stays anonymised for the stores' business data; installed modules anonymise their copies, e.g. order contact snapshots keep only province + country), linked sign-in methods, sessions and links are removed, and Apple sign-in authorizations are revoked in the background. Works in every store of the database. With `core.customer_auth.deletionGraceDays` > 0 at this store the deletion is only scheduled: every session ends at once, the customer gets an email with the date, signing in again before it cancels the deletion, and the account is erased after that many days. 401 `delete_token_invalid` when the link is wrong, used or expired.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delete a customer account with the token from the email", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "token" ] } } } } } }, "/api/v1/storefront/auth/account/delete-request": { "post": { "operationId": "storefrontRequestAccountDeletion", "summary": "Email the signed-in customer a link to delete the account", "description": "The account is deleted only when the link is opened (`storefrontDeleteAccount`): valid for 30 minutes, a newer request invalidates older links. The link goes to the store's domain when the request comes from it (path from `core.customer_auth.deletePath`). 429 when requested too often.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Email the signed-in customer a link to delete the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/auth/email/confirm": { "post": { "operationId": "storefrontConfirmEmail", "summary": "Confirm the customer's email with a verification token", "description": "401 `verify_token_invalid` when the link is wrong, used or expired.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Confirm the customer's email with a verification token", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "token" ] } } } } } }, "/api/v1/storefront/auth/email/verify": { "post": { "operationId": "storefrontRequestEmailVerification", "summary": "Send a verification link to the signed-in customer", "description": "Valid for 24 hours; a newer request invalidates older links. 409 `email_already_verified`, 429 when requested too often.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Send a verification link to the signed-in customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/auth/login": { "post": { "operationId": "storefrontLogin", "summary": "Sign in a customer (storefront)", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sign in a customer (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } } } }, "/api/v1/storefront/auth/logout": { "post": { "operationId": "storefrontLogout", "summary": "Sign out a customer (revokes the refresh token family)", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sign out a customer (revokes the refresh token family)", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } }, "required": [ "refreshToken" ] } } } } } }, "/api/v1/storefront/auth/password": { "post": { "operationId": "storefrontChangePassword", "summary": "Change the signed-in customer's password", "description": "Needs the current `password`. Every session of the customer is revoked and this device gets fresh tokens. 401 `invalid_credentials`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Change the signed-in customer's password", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "newPassword": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "password", "newPassword" ] } } } } } }, "/api/v1/storefront/auth/password/forgot": { "post": { "operationId": "storefrontForgotPassword", "summary": "Request a password reset email (customer)", "description": "Always answers 202, whether or not the email has an account. The link goes to the store's domain when the request comes from it (path from `core.customer_auth.resetPath`) and is valid for 30 minutes. 403 `password_reset_disabled` when the store turned it off; 429 when the IP sends too many.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Request a password reset email (customer)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } }, "required": [ "email" ] } } } } } }, "/api/v1/storefront/auth/password/reset": { "post": { "operationId": "storefrontResetPassword", "summary": "Set a new password with a reset token (customer)", "description": "Consumes the token from the reset email. Every session of the customer is revoked, the email counts as verified. Claiming an account staff created and nobody has claimed yet also links the customer to this store when the email was requested from it; customers who signed up themselves (password, social, phone) are never linked here (signing in links them). 401 `reset_token_invalid`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Set a new password with a reset token (customer)", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 16, "maxLength": 200 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "token", "password" ] } } } } } }, "/api/v1/storefront/auth/phone/code": { "post": { "operationId": "storefrontRequestPhoneCode", "summary": "Text a sign-in code to a phone number (customer)", "description": "Always answers 202, whether or not the number has an account. The 6-digit code is valid for 5 minutes, a newer code replaces older ones, and asking again within 60 seconds sends nothing new. Then call `storefrontPhoneLogin`. 403 `phone_login_disabled` when the store did not turn it on (`core.customer_auth.phoneLogin`), 503 `sms_unavailable` when no SMS account is set up, 400 `phone_invalid`, 429 when the number or IP asks too often.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Text a sign-in code to a phone number (customer)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 6, "maxLength": 32 } }, "required": [ "phone" ] } } } } } }, "/api/v1/storefront/auth/phone/confirm": { "post": { "operationId": "storefrontConfirmPhone", "summary": "Confirm the signed-in customer's phone number with the code", "description": "The number the code was sent to becomes the customer's verified `phone`. 401 `otp_invalid`, 409 `phone_taken`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirm the signed-in customer's phone number with the code", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "phone": { "type": "string" } }, "required": [ "phone" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } } } }, "/api/v1/storefront/auth/phone/login": { "post": { "operationId": "storefrontPhoneLogin", "summary": "Sign in or sign up with a phone number and the texted code", "description": "The number verified on an account signs in to it. A number no account uses creates one (the store must accept sign-ups — 403 `signup_disabled`): send `email` and `name` too; without them 400 `phone_signup_details_required` and the code stays valid, so send it again with them. The new account has no password and its number counts as verified; when the store requires email verification a link is emailed. 409 `email_taken` when the email already has an account (sign in to it, then verify the number there). 401 `otp_invalid` for a wrong, used or expired code (5 wrong tries kill it). 403 `phone_login_disabled`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sign in or sign up with a phone number and the texted code", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "created": { "type": "boolean" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn", "created" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 6, "maxLength": 32 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "phone", "code" ] } } } } } }, "/api/v1/storefront/auth/phone/verify": { "post": { "operationId": "storefrontRequestPhoneVerification", "summary": "Text a code to verify a phone number of the signed-in customer", "description": "Then call `storefrontConfirmPhone` with the code (valid 5 minutes). 409 `phone_taken` when another account already verified this number, 503 `sms_unavailable`, 400 `phone_invalid`, 429 when asked too often.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Text a code to verify a phone number of the signed-in customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 6, "maxLength": 32 } }, "required": [ "phone" ] } } } } } }, "/api/v1/storefront/auth/refresh": { "post": { "operationId": "storefrontRefresh", "summary": "Rotate a customer refresh token", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate a customer refresh token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } }, "required": [ "refreshToken" ] } } } } } }, "/api/v1/storefront/auth/register": { "post": { "operationId": "storefrontRegister", "summary": "Create a customer account (storefront)", "description": "One customer account works in every store of the database. 409 `email_taken` → sign in instead. 403 `signup_disabled` when the store turned sign-up off; the password must meet the store's minimum length (`core.customer_auth`). When the store requires email verification, a verification email is sent and customer-only routes answer 403 `email_not_verified` until the link is opened.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Create a customer account (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] } }, "required": [ "email", "password", "name" ] } } } } } }, "/api/v1/storefront/auth/sessions/revoke-all": { "post": { "operationId": "storefrontRevokeAllSessions", "summary": "Sign the customer out everywhere", "description": "Revokes every session of the customer immediately and returns fresh tokens for this device.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sign the customer out everywhere", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/auth/social/{provider}/exchange": { "post": { "operationId": "storefrontSocialExchange", "summary": "Finish a social sign-in (web redirect flow)", "description": "Consumes `state` once (401 `social_state_invalid` when unknown, used, expired, for another store, or the `flowKey` does not match) and exchanges `code` with the provider. 401 `social_token_invalid` (bad / expired / wrong-audience credential), 403 `social_provider_disabled`, 403 `signup_disabled` (new account while sign-up is off), 403 `account_disabled`, 409 `social_link_required` (an account with this email exists but the provider did not verify the email — sign in and link), 409 `social_email_required` with `details.ticket` (the provider gave no email — collect one and call `storefrontSocialComplete`), 409 `social_login_unsupported` (database not upgraded), 502 `social_provider_unavailable` (retry).", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Finish a social sign-in (web redirect flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "outcome": { "enum": [ "signed_in", "linked", "created" ], "type": "string" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn", "outcome" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 16, "maxLength": 200 }, "code": { "type": "string", "minLength": 1, "maxLength": 4096 }, "flowKey": { "type": "string", "minLength": 16, "maxLength": 200 }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "state", "code", "flowKey" ] } } } } } }, "/api/v1/storefront/auth/social/{provider}/link": { "post": { "operationId": "storefrontSocialLink", "summary": "Link a provider to the signed-in customer (native flow)", "description": "Same credential rules as `storefrontSocialSignIn` (id_token with a nonce, access token, TikTok `authorizationCode` + `codeVerifier` + `redirectUri`, Zalo Mini App `phoneToken`). 409 `social_identity_taken` when the provider account belongs to another customer; linking the same one again is a no-op.", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Link a provider to the signed-in customer (native flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastLoginAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "provider", "email", "createdAt", "lastLoginAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8192 }, "accessToken": { "type": "string", "minLength": 10, "maxLength": 8192 }, "authorizationCode": { "type": "string", "maxLength": 2000 }, "codeVerifier": { "type": "string", "minLength": 43, "maxLength": 128 }, "redirectUri": { "type": "string", "format": "uri", "maxLength": 2000 }, "phoneToken": { "type": "string", "minLength": 10, "maxLength": 8192 } }, "required": [] } } } } } }, "/api/v1/storefront/auth/social/{provider}/link/exchange": { "post": { "operationId": "storefrontSocialLinkExchange", "summary": "Finish linking a provider (redirect flow)", "description": "Must be called by the same customer that started the flow (401 `social_state_invalid` otherwise). 409 `social_identity_taken` when the provider account belongs to another customer; linking the same one again is a no-op.", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Finish linking a provider (redirect flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastLoginAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "provider", "email", "createdAt", "lastLoginAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 16, "maxLength": 200 }, "code": { "type": "string", "minLength": 1, "maxLength": 4096 }, "flowKey": { "type": "string", "minLength": 16, "maxLength": 200 } }, "required": [ "state", "code", "flowKey" ] } } } } } }, "/api/v1/storefront/auth/social/{provider}/link/start": { "post": { "operationId": "storefrontSocialLinkStart", "summary": "Start linking a provider to the signed-in customer (redirect flow)", "description": "Send the browser to `url`. Keep `flowKey` in sessionStorage (never in the URL): the callback page posts `state` + `code` + `flowKey` to `storefrontSocialLinkExchange` within `expiresIn` seconds. `redirectUri` must be on a registered domain of this database (400 `social_redirect_not_allowed`) and registered with the provider. Apple answers with a form POST to `redirectUri` (fields `code`, `state`, `user`). 403 `social_redirect_unavailable` when the store configured only the native flow.", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Start linking a provider to the signed-in customer (redirect flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "state": { "type": "string" }, "flowKey": { "type": "string" }, "expiresIn": { "type": "number" } }, "required": [ "url", "state", "flowKey", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUri": { "type": "string", "format": "uri", "maxLength": 2000 } }, "required": [ "redirectUri" ] } } } } } }, "/api/v1/storefront/auth/social/{provider}/nonce": { "post": { "operationId": "storefrontSocialNonce", "summary": "Get a one-time nonce for a native id_token sign-in", "description": "Google / Apple / Facebook (Limited Login) only. Pass `nonce` to the provider SDK (Apple native apps may pass its SHA-256 hex, as usual), then send the id_token to `storefrontSocialSignIn` within `expiresIn` seconds. Each nonce works once.", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Get a one-time nonce for a native id_token sign-in", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "nonce": { "type": "string" }, "expiresIn": { "type": "number" } }, "required": [ "nonce", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/auth/social/{provider}/start": { "post": { "operationId": "storefrontSocialStart", "summary": "Start a social sign-in (web redirect flow)", "description": "Send the browser to `url`. Keep `flowKey` in sessionStorage (never in the URL): the callback page posts `state` + `code` + `flowKey` to `storefrontSocialExchange` within `expiresIn` seconds. `redirectUri` must be on a registered domain of this database (400 `social_redirect_not_allowed`) and registered with the provider. Apple answers with a form POST to `redirectUri` (fields `code`, `state`, `user`). 403 `social_redirect_unavailable` when the store configured only the native flow.", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Start a social sign-in (web redirect flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "url": { "type": "string" }, "state": { "type": "string" }, "flowKey": { "type": "string" }, "expiresIn": { "type": "number" } }, "required": [ "url", "state", "flowKey", "expiresIn" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUri": { "type": "string", "format": "uri", "maxLength": 2000 } }, "required": [ "redirectUri" ] } } } } } }, "/api/v1/storefront/auth/social/{provider}/token": { "post": { "operationId": "storefrontSocialSignIn", "summary": "Sign in with a provider credential from its SDK (native flow)", "description": "Google / Apple: `idToken` (its `nonce` claim must be a nonce from `storefrontSocialNonce`, 401 `social_nonce_invalid` otherwise). Facebook: `accessToken`, or the Limited Login `idToken` (with a nonce, as above). Zalo: `accessToken` (must belong to the store's app). TikTok (mobile SDK): `authorizationCode` + `codeVerifier` + `redirectUri` exactly as the SDK used them. Zalo Mini App: `accessToken` from `getAccessToken()`, and optionally `phoneToken` from `getPhoneNumber()` (401 `social_phone_token_invalid` when it is used or expired) — the verified number fills the customer's empty phone, never replaces one. `name` is an unsigned hint (Apple sends the name only on the first authorization) used only when the provider gives none. Apple: also send the SDK's `authorizationCode` — the server keeps the resulting token so it can revoke the authorization when the customer deletes the account (required by Apple); a bad code does not block sign-in. `outcome`: `created` (new account), `signed_in`, or `linked` (joined the existing account with the same provider-verified email). 401 `social_token_invalid` (bad / expired / wrong-audience credential), 403 `social_provider_disabled`, 403 `signup_disabled` (new account while sign-up is off), 403 `account_disabled`, 409 `social_link_required` (an account with this email exists but the provider did not verify the email — sign in and link), 409 `social_email_required` with `details.ticket` (the provider gave no email — collect one and call `storefrontSocialComplete`), 409 `social_login_unsupported` (database not upgraded), 502 `social_provider_unavailable` (retry).", "tags": [ "auth" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sign in with a provider credential from its SDK (native flow)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "outcome": { "enum": [ "signed_in", "linked", "created" ], "type": "string" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn", "outcome" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8192 }, "accessToken": { "type": "string", "minLength": 10, "maxLength": 8192 }, "authorizationCode": { "type": "string", "maxLength": 2000 }, "codeVerifier": { "type": "string", "minLength": 43, "maxLength": 128 }, "redirectUri": { "type": "string", "format": "uri", "maxLength": 2000 }, "phoneToken": { "type": "string", "minLength": 10, "maxLength": 8192 }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/storefront/auth/social/complete": { "post": { "operationId": "storefrontSocialComplete", "summary": "Finish a social sign-up with an email address", "description": "After 409 `social_email_required`: creates the account with the provider identity from `ticket` and the `email` the customer typed (not verified — a verification link is sent when the store requires it). 409 `email_taken` (the ticket stays valid: sign in to that account and link instead, or use another email), 401 `social_ticket_invalid`, 403 `signup_disabled`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Finish a social sign-up with an email address", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "outcome": { "enum": [ "signed_in", "linked", "created" ], "type": "string" } }, "required": [ "customerId", "accessToken", "refreshToken", "tokenType", "expiresIn", "outcome" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string", "minLength": 16, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "ticket", "email" ] } } } } } }, "/api/v1/storefront/auth/social/providers": { "get": { "operationId": "storefrontSocialProviders", "summary": "Social sign-in providers available at this store", "description": "Render a button per provider. `clientId` is public (Google / Apple client id, Facebook / Zalo / Zalo Mini App app id, TikTok client key) for the provider's SDK. `redirect` = the web redirect flow is configured; `nonce` = the native flow accepts an OIDC id_token that needs `storefrontSocialNonce` first (Facebook: only Limited Login). `zalo_miniapp` is the sign-in inside a Zalo Mini App (native only); its identity is stored as `zalo`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Social sign-in providers available at this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "enum": [ "google", "apple", "facebook", "zalo", "tiktok", "zalo_miniapp" ], "type": "string" }, "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirect": { "type": "boolean" }, "nonce": { "type": "boolean" } }, "required": [ "provider", "clientId", "redirect", "nonce" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/brands": { "get": { "operationId": "listPublicBrands", "summary": "List active brands (storefront)", "description": "Active brands of the store, in the request language. Brands without any translation are hidden. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "brands" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List active brands (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "code", "websiteUrl", "logoFileInfo", "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/brands/{slug}": { "get": { "operationId": "getPublicBrandBySlug", "summary": "Get an active brand by slug (storefront)", "description": "Matches the slug of any translation (the request language first); 404 `brand_not_found` when no active brand has it.", "tags": [ "brands" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get an active brand by slug (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "code", "websiteUrl", "logoFileInfo", "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/cart": { "get": { "operationId": "getMyCart", "summary": "Get my cart (storefront)", "description": "Signed-in customer's cart, or — without a customer token — the guest cart of the `x-cart-token` request header (401 `cart_sign_in_required` where guest carts are not available yet). Only a token that points to an open guest cart counts; a malformed, unknown or merged token is ignored (a creating call then issues a new `cartToken`). Returns the whole cart priced again (catalog price per unit, offers, taxes, discounts — nothing is held). Lines no longer on sale move to `unavailable` with the reason; saved codes no longer accepted move to `rejectedCodes`. Errors of one cart line carry `error.at = items.`. `id: null` = no cart yet.", "tags": [ "cart" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get my cart (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/cart/codes": { "put": { "operationId": "setMyCartCodes", "summary": "Set the codes of my cart (storefront)", "description": "Signed-in customer's cart, or — without a customer token — the guest cart of the `x-cart-token` request header (401 `cart_sign_in_required` where guest carts are not available yet). Only a token that points to an open guest cart counts; a malformed, unknown or merged token is ignored (a creating call then issues a new `cartToken`). Replaces the codes (discount, referral…; upper-cased). A code no installed module accepts → 400 `price_code_not_recognized` (nothing saved). Codes on a cart without priceable lines (no cart yet, empty, or every line in `unavailable`) → 409 `cart_empty`. Each NEW code (not already saved) is one guess: too many wrong guesses from this customer / cart or this IP in the store, or fewer guesses left than NEW codes → 429 `too_many_attempts` (`details.retryAfter`, header `retry-after`) before checking — retry with fewer new codes or wait. Removing codes (a subset of the saved ones, `codes: []` included) is never counted nor blocked. A guest without a cart token sending `codes: []` gets a new empty guest cart (`cartToken` returned once). A new guest cart over the store's hourly cap (setting `cart.guest_carts`) → 429 `cart_guest_limit` (`details.retryAfter`, header `retry-after`). Returns the whole cart priced again (catalog price per unit, offers, taxes, discounts — nothing is held). Lines no longer on sale move to `unavailable` with the reason; saved codes no longer accepted move to `rejectedCodes`. Errors of one cart line carry `error.at = items.`.", "tags": [ "cart" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Set the codes of my cart (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": [ "codes" ] } } } } } }, "/api/v1/storefront/cart/items": { "post": { "operationId": "addMyCartItem", "summary": "Add to my cart (storefront)", "description": "Signed-in customer's cart, or — without a customer token — the guest cart of the `x-cart-token` request header (401 `cart_sign_in_required` where guest carts are not available yet). Only a token that points to an open guest cart counts; a malformed, unknown or merged token is ignored (a creating call then issues a new `cartToken`). A guest without a cart token gets a new guest cart: `cartToken` is returned ONCE — send it as `x-cart-token` from then on. Adds a variant in a unit (`uomId`, null = base unit); the same variant + unit adds up. The line must be priceable now (409 `price_variant_unavailable`, 400 `price_uom_invalid` / `price_qty_not_exact`); at most 100 lines (409 `cart_full`). A new guest cart over the store's hourly cap (setting `cart.guest_carts`) → 429 `cart_guest_limit` (`details.retryAfter`, header `retry-after`). Returns the whole cart priced again (catalog price per unit, offers, taxes, discounts — nothing is held). Lines no longer on sale move to `unavailable` with the reason; saved codes no longer accepted move to `rejectedCodes`. Errors of one cart line carry `error.at = items.`.", "tags": [ "cart" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Add to my cart (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "qty" ] } } } } } }, "/api/v1/storefront/cart/items/{itemId}": { "patch": { "operationId": "setMyCartItemQty", "summary": "Change a line quantity (storefront)", "description": "Signed-in customer's cart, or — without a customer token — the guest cart of the `x-cart-token` request header (401 `cart_sign_in_required` where guest carts are not available yet). Only a token that points to an open guest cart counts; a malformed, unknown or merged token is ignored (a creating call then issues a new `cartToken`). 404 `cart_item_not_found`. Returns the whole cart priced again (catalog price per unit, offers, taxes, discounts — nothing is held). Lines no longer on sale move to `unavailable` with the reason; saved codes no longer accepted move to `rejectedCodes`. Errors of one cart line carry `error.at = items.`.", "tags": [ "cart" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Change a line quantity (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "qty" ] } } } } }, "delete": { "operationId": "removeMyCartItem", "summary": "Remove a line (storefront)", "description": "Signed-in customer's cart, or — without a customer token — the guest cart of the `x-cart-token` request header (401 `cart_sign_in_required` where guest carts are not available yet). Only a token that points to an open guest cart counts; a malformed, unknown or merged token is ignored (a creating call then issues a new `cartToken`). 404 `cart_item_not_found`. Returns the whole cart priced again (catalog price per unit, offers, taxes, discounts — nothing is held). Lines no longer on sale move to `unavailable` with the reason; saved codes no longer accepted move to `rejectedCodes`. Errors of one cart line carry `error.at = items.`.", "tags": [ "cart" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove a line (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/cart/merge": { "post": { "operationId": "mergeMyCart", "summary": "Move a guest cart into my cart (storefront)", "description": "After signing in: moves the lines and codes of the guest cart of `cartToken` into the signed-in customer's cart (same variant + unit adds up; the customer's cart is created when missing) and deletes the guest cart — then forget the token. Unknown / already merged token or another store's token → nothing moves. More than 100 lines together → 409 `cart_full` (nothing moved). Returns the whole cart priced again (catalog price per unit, offers, taxes, discounts — nothing is held). Lines no longer on sale move to `unavailable` with the reason; saved codes no longer accepted move to `rejectedCodes`. Errors of one cart line carry `error.at = items.`.", "tags": [ "cart" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Move a guest cart into my cart (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cartToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "cartToken" ] } } } } } }, "/api/v1/storefront/checkout/confirm": { "post": { "operationId": "confirmMyCheckout", "summary": "Place the order from my cart (storefront)", "description": "In ONE transaction: re-prices the cart (nothing dropped: a line no longer on sale fails with `error.at = items.`, a rejected code with 400 `price_code_not_recognized`), lets extension modules hold what they need (`checkout.before_confirm`), places the order (stock reserved in the store's default warehouse; short stock → 409 `stock_insufficient_available` with `error.at = items.`), creates the payment intent and closes the cart. Pay the intent with `paymentCode` through the storefront payment routes; the order confirms itself when paid. Calling again → 409 `checkout_cart_empty` (no second order). `paymentMethod`: `prepaid` (default) or `cod` when the store accepts cash on delivery (`checkout.payment_methods`) — otherwise 409 `checkout_cod_disabled`; an order total above `codMaxTotal` → 409 `checkout_cod_over_limit` (`details.max`). A COD order is not cancelled when its payment intent expires; the carrier's remitted cash pays it. A zero-total order is always `prepaid` (already paid).", "tags": [ "checkout" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Place the order from my cart (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "paymentCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "type": "string" }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "paymentCode", "customerName", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] }, "paymentCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "order", "paymentCode" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "line2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "line1", "country" ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" } }, "required": [ "shippingAddress" ] } } } } } }, "/api/v1/storefront/checkout/preview": { "post": { "operationId": "previewMyCheckout", "summary": "Preview checkout (storefront)", "description": "The cart priced with the store's shipping fee (`checkout.shipping`: flat fee, free from a goods total). Nothing is held. 409 `checkout_cart_empty`.", "tags": [ "checkout" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview checkout (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string" } }, "rejectedCodes": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "reason" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "anyOf": [ { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] }, { "type": "null" } ] }, "cartToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "currency", "codes", "rejectedCodes", "lines", "unavailable", "adjustments", "totals", "cartToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/configs": { "get": { "operationId": "getStorefrontConfigs", "summary": "Public settings", "description": "Effective values of the settings marked public (sign-in options, customer account options) for the store of the request (`x-store` or the domain). Never contains secrets.", "tags": [ "configs" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/me": { "get": { "operationId": "storefrontMe", "summary": "The signed-in customer", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The signed-in customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "phoneVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "store": { "type": "string" } }, "required": [ "id", "email", "name", "phone", "emailVerifiedAt", "phoneVerifiedAt", "store" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/me/identities": { "get": { "operationId": "storefrontListIdentities", "summary": "Social sign-in methods linked to the signed-in customer", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Social sign-in methods linked to the signed-in customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastLoginAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "provider", "email", "createdAt", "lastLoginAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/me/identities/{id}": { "delete": { "operationId": "storefrontUnlinkIdentity", "summary": "Remove a linked social sign-in method", "description": "409 `social_last_login_method` when it is the only way to sign in and the customer has no password (set one with the password reset email first). 404 `social_identity_not_found`.", "tags": [ "me" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Remove a linked social sign-in method", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/orders": { "get": { "operationId": "listMyOrders", "summary": "List my orders (storefront)", "description": "Orders of the signed-in customer in this store, newest first. Cursor-paginated.", "tags": [ "orders" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: placed, confirmed, fulfilled, completed, cancelled" }, "description": "eq: one of: placed, confirmed, fulfilled, completed, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List my orders (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "paymentCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "paymentCode" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/orders/{id}": { "get": { "operationId": "getMyOrder", "summary": "Get one of my orders (storefront)", "description": "404 `order_not_found` for an order of someone else.", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get one of my orders (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "paymentCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "type": "string" }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "paymentCode", "customerName", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/orders/{id}/cancel": { "post": { "operationId": "cancelMyOrder", "summary": "Cancel one of my orders (storefront)", "description": "Only while the order is still `placed` and unpaid (409 `order_invalid_transition` / `order_paid_cancel`): releases the reserved stock and cancels the payment intent.", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel one of my orders (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "paymentCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerName": { "type": "string" }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "paymentCode", "customerName", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/storefront/payments/intents/{id}": { "get": { "operationId": "getStorefrontPaymentIntent", "summary": "Payment details of an intent", "description": "What the buyer owes and how to pay: bank transfer with the payment `code` as content + VietQR image (`transfer`), and whether MoMo is available (`momo`). Needs the intent id and its `code`; a wrong pair is 404 `payment_intent_not_found`. Poll it to see `status` turn `paid`; once paid, `einvoice` carries the store's VAT e-invoice (number, tax authority code, PDF) when the store issues them.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 16 } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment details of an intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAt", "description", "expiresAt", "transfer", "momo", "einvoice" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/payments/intents/{id}/momo": { "post": { "operationId": "createStorefrontPaymentMomoCheckout", "summary": "Pay an intent with MoMo", "description": "Creates a MoMo order for the intent (id + `code`) and returns where to pay (`payUrl`, `deeplink`, `qrCodeUrl`). The intent becomes `paid` when MoMo confirms. 404 `payment_intent_not_found`, 409 `payment_provider_not_configured` / `payment_intent_not_payable`, 400 `momo_amount_out_of_range`, 502 `momo_rejected`, 503 `momo_unavailable`.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pay an intent with MoMo", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "intentId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "payUrl": { "type": "string" }, "deeplink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qrCodeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "intentId", "orderId", "amount", "currency", "payUrl", "deeplink", "qrCodeUrl", "expiresAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 16 } }, "required": [ "code" ] } } } } } }, "/api/v1/storefront/product-categories": { "get": { "operationId": "listPublicProductCategories", "summary": "List visible product categories (storefront)", "description": "Active, translated categories of the store whose ancestors are all active, in the request language. Build the tree from `parentId`; the default `sort=tree` returns parents first, siblings by `sortOrder` then code. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "product-categories" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "tree", "-tree", "sort_order", "-sort_order", "code", "-code", "path", "-path", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `tree`" }, "description": "Sort field; prefix `-` for descending. Default `tree`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: product_categories.code, product_category_translations.name" }, "description": "Case-insensitive substring search in: product_categories.code, product_category_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "parent_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "parent_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: int" }, "description": "eq: int" }, { "name": "depth.lte", "in": "query", "required": false, "schema": { "type": "string", "description": "lte: int" }, "description": "lte: int" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List visible product categories (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "parentId", "parentInfo", "path", "depth", "code", "imageFileInfo", "sortOrder", "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/product-categories/{slug}": { "get": { "operationId": "getPublicProductCategoryBySlug", "summary": "Get a visible product category by slug (storefront)", "description": "Matches the slug of any translation (the request language first); 404 `product_category_not_found` when no visible category has it.", "tags": [ "product-categories" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a visible product category by slug (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "parentId", "parentInfo", "path", "depth", "code", "imageFileInfo", "sortOrder", "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/products": { "get": { "operationId": "listPublicProducts", "summary": "List products on sale (storefront)", "description": "Active, translated products of the store that have at least one active variant, in the request language, with their active variants and prices per unit (no long description / SEO fields: see GET /storefront/products/{slug}). At most 50 per page. `brandInfo` / `categoryInfo` are null when the brand / category is hidden from the storefront. `in_category` = a category and all of its sub-categories. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: products.code, product_translations.name" }, "description": "Case-insensitive substring search in: products.code, product_translations.name" }, { "name": "featured", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "brand_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "brand_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "category_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "in_category", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Category id: products in that category OR any of its sub-categories (AND-ed with the other filters, e.g. `category_id`)" }, "description": "Category id: products in that category OR any of its sub-categories (AND-ed with the other filters, e.g. `category_id`)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List products on sale (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "featured": { "type": "boolean" }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "slug" ] }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "slug" ] }, { "type": "null" } ] }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileInfo", "sortOrder" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } } }, "required": [ "id", "sku", "price", "compareAtPrice", "currency", "options", "unitPrices" ] } } }, "required": [ "id", "code", "featured", "brandInfo", "categoryInfo", "baseUomInfo", "lang", "name", "shortDescription", "slug", "images", "variants" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/products/{slug}": { "get": { "operationId": "getPublicProductBySlug", "summary": "Get a product on sale by slug (storefront)", "description": "Matches the slug of any translation (the request language first); 404 `product_not_found` when no product on sale has it.", "tags": [ "products" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a product on sale by slug (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "featured": { "type": "boolean" }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "slug" ] }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "slug" ] }, { "type": "null" } ] }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileInfo", "sortOrder" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } } }, "required": [ "id", "sku", "price", "compareAtPrice", "currency", "options", "unitPrices" ] } } }, "required": [ "id", "code", "featured", "brandInfo", "categoryInfo", "baseUomInfo", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "images", "variants" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/products/images/{fileId}": { "get": { "operationId": "getPublicProductImage", "summary": "Get a product image (storefront)", "description": "The bytes of an image attached to a product on sale (the `fileInfo.id` of `images[]`), for . Only raster images (PNG, JPEG, WebP, GIF, AVIF); 404 `product_image_not_found` when the file is not an image of a visible product of this store, or not a raster image. Served inline with nosniff and a sandboxing CSP; cacheable for 5 minutes; `ETag` = the SHA-256 of the file (304 on `If-None-Match`).", "tags": [ "products" ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a product image (storefront)", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "etag": { "description": "Quoted SHA-256 of the file", "schema": { "type": "string" } }, "cache-control": { "description": "`public, max-age=300`", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/return-requests": { "get": { "operationId": "listMyReturnRequests", "summary": "My return requests (storefront)", "description": "Return requests of the signed-in customer, newest first. Filter by `status` / `order_id`. Cursor-paginated.", "tags": [ "return-requests" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: return_requests.number" }, "description": "Case-insensitive substring search in: return_requests.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: requested, approved, received, refunded, closed, rejected, cancelled" }, "description": "eq: one of: requested, approved, received, refunded, closed, rejected, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "My return requests (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "number", "status", "orderId", "orderInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createMyReturnRequest", "summary": "Ask to return items of my order (storefront)", "description": "For one of MY delivered orders (404 `return_request_order_not_found` otherwise; 409 `return_request_order_not_returnable` when not delivered yet). Lines: `orderItemId` (the `items[].id` of the order) + `qty` in that line's unit, at most what is still returnable (409 `return_request_qty_exceeded`, `details.available`; `error.at = items.`). The store then approves or rejects it.", "tags": [ "return-requests" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Ask to return items of my order (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "number", "status", "orderId", "orderInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "items": { "type": "array", "items": { "type": "object", "properties": { "orderItemId": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "orderItemId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "orderId", "reason", "items" ] } } } } } }, "/api/v1/storefront/return-requests/{id}": { "get": { "operationId": "getMyReturnRequest", "summary": "One of my return requests (storefront)", "description": "404 `return_request_not_found` when it is not yours.", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One of my return requests (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "number", "status", "orderId", "orderInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/return-requests/{id}/cancel": { "post": { "operationId": "cancelMyReturnRequest", "summary": "Cancel my return request (storefront)", "description": "While `requested` / `approved` (409 `return_request_invalid_status` after that).", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel my return request (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "number", "status", "orderId", "orderInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/shipments": { "get": { "operationId": "listMyShipments", "summary": "Shipments of one of my orders (storefront)", "description": "Tracking of the shipments of `order_id` — an order of the signed-in customer (another order → empty list). Oldest first, at most 50.", "tags": [ "shipments" ], "parameters": [ { "name": "order_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shipments of one of my orders (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "number", "carrier", "trackingNumber", "status", "currency", "codAmount", "shippedAt", "deliveredAt", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/store": { "get": { "operationId": "getStorefrontStore", "summary": "The store of the request", "description": "Public facts of the store the request resolved to (domain, `x-store` or `Origin`): name, time zone, default currency and content languages. Build the language switcher from `languages` (always contains `defaultLang`) instead of hard-coding it; send the chosen one as `x-lang`. No internal ids.", "tags": [ "store" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The store of the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "defaultLang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "timezone", "currency", "defaultLang", "languages" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "bearer": [] } ] } }, "/api/v1/storefront/wishlist": { "get": { "operationId": "listMyWishlist", "summary": "My wishlist (storefront)", "description": "Variants the signed-in customer saved, newest first. `onSale: false` = no longer on sale (variant off, product not active or in the trash): `variantInfo` is then null — show it as unavailable and let the customer remove it. Cursor-paginated.", "tags": [ "wishlist" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "My wishlist (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "onSale": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "variantId", "variantInfo", "onSale", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "addMyWishlistItem", "summary": "Save a variant to my wishlist (storefront)", "description": "Idempotent: saving a variant already saved returns the existing item. The variant must be on sale — 409 `wishlist_variant_unavailable` also when it does not exist in the store; at most 500 items (409 `wishlist_full`). 404 `wishlist_item_not_found` only when another request removed it at the same moment.", "tags": [ "wishlist" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Save a variant to my wishlist (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "onSale": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "variantId", "variantInfo", "onSale", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" } }, "required": [ "variantId" ] } } } } } }, "/api/v1/storefront/wishlist/{variantId}": { "delete": { "operationId": "removeMyWishlistItem", "summary": "Remove a variant from my wishlist (storefront)", "description": "By VARIANT id (the heart toggle knows the variant). 404 `wishlist_item_not_found` when it is not saved.", "tags": [ "wishlist" ], "parameters": [ { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Remove a variant from my wishlist (storefront)", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/storefront/wishlist/check": { "post": { "operationId": "checkMyWishlist", "summary": "Which variants are in my wishlist (storefront)", "description": "Read-only. Sends up to 100 `variantIds`; returns those the customer saved — e.g. to fill the heart icons of a product grid.", "tags": [ "wishlist" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name or Origin is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; optional when the domain or Origin is mapped to a store", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Which variants are in my wishlist (storefront)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "variantIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "variantIds" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 } }, "required": [ "variantIds" ] } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "Error": { "description": "Error envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "at": { "type": "string", "description": "Element of the request body that caused the error, e.g. `lines.3` (multi-line operations)" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "security": [ { "bearer": [] } ] }