> ## Documentation Index > Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create an order and get the payment redirect > Creates the order and the payment session; redirect the buyer to `redirectUrl`. Several lines (up to 20) = a payment group: one order per line (`orderIds`), one provider transaction for the total, `orderId` = `groupId` (returned in `itemshop_order`). Method amount limits apply to the total. Retrying with the same `Idempotency-Key` and the same body returns the same order/group. ## OpenAPI ````yaml /openapi.en.json post /api/v2/storefront/v1/shops/{shopId}/checkout openapi: 3.0.0 info: title: ItemShop v2 API description: >- REST API platformy ItemShop v2 (NestJS + Fastify). Wszystkie ścieżki mają prefiks /api/v2. version: 2.0.0 contact: {} servers: - url: https://itemshop.dev description: Production (API under /api/v2, same origin as the panel) - url: http://localhost:3000 description: Local security: [] tags: [] paths: /api/v2/storefront/v1/shops/{shopId}/checkout: post: tags: - Storefront v1 summary: Create an order and get the payment redirect description: >- Creates the order and the payment session; redirect the buyer to `redirectUrl`. Several lines (up to 20) = a payment group: one order per line (`orderIds`), one provider transaction for the total, `orderId` = `groupId` (returned in `itemshop_order`). Method amount limits apply to the total. Retrying with the same `Idempotency-Key` and the same body returns the same order/group. operationId: createCheckout parameters: - name: shopId required: true in: path description: >- Shop ID (ObjectId). Also accepts the `uniqueName`, an active custom domain or `.`. schema: type: string example: 664f1a2b3c4d5e6f7a8b9c0d - name: cf-turnstile-response in: header description: >- Cloudflare Turnstile token. Optional; required only after a burst of attempts from one IP (`CAPTCHA_REQUIRED`). required: false schema: type: string - name: Idempotency-Key in: header description: >- Random attempt key (32–128 chars `[A-Za-z0-9_-]`, e.g. a UUID). Reuse only for an identical retry. required: true schema: type: string example: 3b0f6f1e-9c2a-4d1b-8a52-1f0e2c7d9a44 requestBody: content: application/json: schema: $ref: '#/components/schemas/StorefrontCheckoutDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/StorefrontCheckoutResponseDto' '400': description: >- `VALIDATION_FAILED`, `IDEMPOTENCY_KEY_REQUIRED`, `LEGAL_CONSENT_REQUIRED`, `DISCOUNT_INVALID`, `SHOP_PAYMENT_NOT_READY`, `PAYMENT_INIT_FAILED`, `RETURN_URL_NOT_ALLOWED`, `EMAIL_REQUIRED` (produkt z treścią cyfrową / digital product), `INVALID_QUANTITY` (>100 kluczy / keys)… content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '403': description: Origin outside the shop domains (`ORIGIN_NOT_ALLOWED`) content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '404': description: >- Shop/resource not found or the shop is blocked (`SHOP_NOT_FOUND`, `PRODUCT_NOT_FOUND`, `ORDER_NOT_FOUND`) content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '409': description: >- `LEGAL_DOCUMENTS_CHANGED`, `IDEMPOTENCY_KEY_REUSED`, `CHECKOUT_IN_PROGRESS`, `CHECKOUT_ATTEMPT_CLOSED`, `OUT_OF_STOCK` content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' '429': description: Rate limit exceeded (`RATE_LIMITED`) content: application/json: schema: $ref: '#/components/schemas/StorefrontErrorDto' components: schemas: StorefrontCheckoutDto: type: object properties: items: minItems: 1 maxItems: 20 description: >- Cart lines (1–20). Several lines = a payment group: one order per line and one payment for the total (adr/0002) type: array items: $ref: '#/components/schemas/StorefrontCartItemDto' nick: type: string pattern: ^[a-zA-Z0-9_]{3,16}$ description: >- Player nick. Required when `shop.kind = game` (or the product runs `{PLAYER}` commands) — otherwise `NICK_REQUIRED` example: Steve email: type: string format: email minLength: 3 maxLength: 254 description: >- Buyer email. Required without a nick (`general` shop) — it then identifies the buyer; otherwise `EMAIL_REQUIRED` example: gracz@example.com discountCode: type: string minLength: 1 maxLength: 50 pattern: ^[A-Za-z0-9_-]+$ example: LATO10 consents: $ref: '#/components/schemas/StorefrontConsentsDto' paymentMethodCode: type: string minLength: 1 maxLength: 100 pattern: ^[^:]+$ description: Required for paid orders (from `payment-methods`) example: imoje paymentChannel: type: string minLength: 1 maxLength: 60 description: Method channel (from `payment-methods[].channel`) example: blik returnUrl: type: string format: uri minLength: 1 maxLength: 2048 description: >- Where the gateway sends the buyer back. Must be on a shop domain (or a preview / localhost). The platform sets the query parameter `itemshop_order=` and drops any fragment (`#…`); read it from `location.search`. Without returnUrl — the platform-hosted shop status page. example: https://moj-sklep.pl/dziekujemy required: - items - consents StorefrontCheckoutResponseDto: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/StorefrontCheckoutResultDto' required: - success - data StorefrontErrorDto: type: object properties: success: type: boolean example: false statusCode: type: number example: 404 code: enum: - VALIDATION_FAILED - BAD_REQUEST - NOT_FOUND - SHOP_NOT_FOUND - PRODUCT_NOT_FOUND - ORDER_NOT_FOUND - PRODUCT_UNAVAILABLE - PRODUCT_VARIANT_REQUIRED - INVALID_PRODUCT_VARIANT - INVALID_QUANTITY - OUT_OF_STOCK - CART_EMPTY - NICK_REQUIRED - EMAIL_REQUIRED - CART_TOO_LARGE - DISCOUNT_INVALID - LEGAL_CONSENT_REQUIRED - LEGAL_DOCUMENTS_CHANGED - SHOP_PAYMENT_NOT_READY - PAYMENT_INIT_FAILED - ORDER_BLOCKED - RETURN_URL_NOT_ALLOWED - VOUCHER_NOT_FOUND - VOUCHER_USED - VOUCHER_EXPIRED - IDEMPOTENCY_KEY_REQUIRED - IDEMPOTENCY_KEY_REUSED - CHECKOUT_ATTEMPT_CLOSED - CHECKOUT_IN_PROGRESS - CAPTCHA_REQUIRED - ORIGIN_NOT_ALLOWED - FORBIDDEN - UNAUTHORIZED - PAYLOAD_TOO_LARGE - CONFLICT - RATE_LIMITED - SERVICE_UNAVAILABLE - INTERNAL_ERROR type: string description: Machine-readable error code — translate UI messages by this example: SHOP_NOT_FOUND message: type: string description: >- Developer message (language not guaranteed; do not show it to buyers) example: Shop not found error: type: string description: Same as `message` (compatibility with the rest of the API) example: Shop not found deprecated: true details: type: object description: Validation details timestamp: type: string format: date-time example: '2026-10-27T12:00:00.000Z' path: type: string example: /api/v2/storefront/v1/shops/moj-sklep required: - success - statusCode - code - message - error - timestamp - path StorefrontCartItemDto: type: object properties: productId: type: string example: 664f1a2b3c4d5e6f7a8b9c0d quantity: type: number minimum: 1 maximum: 100000 example: 1 default: 1 variantId: type: string description: >- `variants[].id` (one of variantId/variant required when pricingMode = variants) example: 664f1a2b3c4d5e6f7a8b9c11 variant: type: string minLength: 1 maxLength: 80 description: Variant name (instead of variantId) example: 30 dni required: - productId StorefrontConsentsDto: type: object properties: terms: type: boolean description: Seller terms accepted example: true immediateDelivery: type: boolean description: >- Combined consent: request immediate delivery of digital content + acknowledge losing the right of withdrawal example: true legalVersion: type: string pattern: ^[a-f0-9]{64}$ description: The shop `legal.version` shown to the buyer example: a3f1c20000000000000000000000000000000000000000000000000000000000 required: - terms - immediateDelivery - legalVersion StorefrontCheckoutResultDto: type: object properties: orderId: type: string description: >- Identifier for the status page and `itemshop_order`: the order ID, or for several lines the payment group ID example: 664f1a2b3c4d5e6f7a8b9c0d orderNumber: type: string description: Order or group number example: A1B2C3D4 statusKey: type: string description: >- Status page secret: `GET /orders/by-number/{orderNumber}/status?key=`. Show it only to the buyer; it also comes back in the return URL as `itemshop_key` example: k3m9x2p7qa status: type: string enum: - pending - paid - processing - completed - cancelled - failed - dispute example: pending groupId: type: string nullable: true description: Payment group (several lines) — then equal to `orderId` example: null orderIds: description: Line orders in `items[]` order example: - 664f1a2b3c4d5e6f7a8b9c0d type: array items: type: string redirectUrl: type: string description: >- Redirect the buyer here (gateway, or the status page for free orders) example: https://pay.imoje.pl/… free: type: boolean description: Free order (100% discount) — already paid, no gateway example: false required: - orderId - orderNumber - statusKey - status - groupId - orderIds - redirectUrl - free ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.