Mutations overview | DoSwiftly Docs

📄️ cartAddLines

Add one or more lines to the cart. Adding the same variant a second time merges into the existing line (sums the quantity). Returns the full updated cart plus any non-fatal warnings (e.g. stock dropped below requested quantity).

📄️ cartApplyGiftCard

Apply a gift card to the cart by full code. The card is debited at cartComplete. Rate-limited to 5 requests per minute per IP+shop (gift card codes form a finite enumerable space).

📄️ cartClearPaymentSelection

Clear all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows in the storefront UI. Idempotent — calling twice yields the same end state. The cart must be ACTIVE (CONVERTED carts reject with ALREADY_COMPLETED).

📄️ cartComplete

Finalise the cart into an Order. The cart is locked and no longer accepts mutations. Payment is initiated separately via paymentCreate — check order.canCreatePayment to decide whether to render a "Pay now" button or send the buyer directly to the confirmation page (for offline methods such as cash on delivery). Rate-limited to 5 requests per minute per IP+shop; pass an idempotencyKey to guard against duplicate orders on retry.

📄️ cartCreate

Create a new cart. All fields on input are optional — call with no input to create an empty cart, or pass initial lines, buyer identity, attributes, discount codes, email and a shipping address to skip the corresponding follow-up calls.

📄️ cartDiscountCodesUpdate

Replace (not merge) the list of discount codes on the cart. Pass an empty array to clear all codes. Rate-limited to 10 requests per minute per IP+shop.

📄️ cartDowngradeOnLogout

Downgrade a cart to guest on logout — clears the customer association, contact details, addresses and payment selection, but keeps the line items, discount codes, selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow (with the cart secret) before tearing down the auth session; the next person on a shared device then sees none of the previous buyer's data.

📄️ cartMerge

Merge a guest cart into the signed-in customer's existing cart on login. Call right after authenticating, passing the guest cart id (its secret travels in the cart credential header). Line quantities are summed per variant and the buyer's in-session checkout fields win. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid. Requires authentication (CARTMERGEREQUIRESAUTH otherwise); refuses carts in different currencies (CARTCURRENCY_MISMATCH).

📄️ cartRecoveryRedeem

Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token from the link; on success the cart is recovered and its access secret is ROTATED — the NEW secret is returned once in secret (persist it; the previous one no longer works), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant sends the link, never takes over the cart. Returns CARTRECOVERYLINKEXPIRED / CARTRECOVERYLINKINVALID for a bad link (no cart content is exposed) and CARTNOTFOUND when the cart no longer exists.

📄️ cartRemoveGiftCard

Remove a previously applied gift card from the cart by its CartAppliedGiftCard.id. The storefront never has to handle the full gift card code on the client.

📄️ cartRemoveLines

Remove one or more lines from the cart by CartLine.id. Equivalent to cartUpdateLines with quantity: 0 but lets the storefront express the intent explicitly.

📄️ cartSelectPaymentMethod

Select a payment method on the cart by category (BLIK, CARD, BANK_TRANSFER, ...). Backend resolves the preferred provider from MerchantPaymentConfig at paymentCreate time. Optional preferredProvider overrides the merchant priority when the buyer explicitly picks a gateway from PaymentMethod.providersAvailable. Optional preferredInstrument enables instrument-level deep-link na gateway hosted page (BLIK ekran, mBank flow, etc.) — wymaga preferredProvider.

📄️ cartSelectShippingMethod

Select a shipping method on the cart. Validates the method against the cart contents and the shipping address (must be eligible for the destination, and a pickup point must be set when the method delivers to a locker / collection point). Updates cost.totalShipping and the grand total.

📄️ cartSetBillingAddress

Set the billing address on a cart. The shipping address is left unchanged — pass billing only when it differs from shipping (otherwise the order mirrors the shipping address as the billing address).

📄️ cartSetShippingAddress

Set the shipping address on a cart. Pass address.pickupPoint when the buyer is delivering to a parcel locker / collection point — required for non-HOME shipping methods. Replaces any previous shipping address; the billing address is left untouched.

📄️ cartUpdateAttributes

Replace (not merge) the cart-level custom attributes — free-form key/value pairs surfaced to the merchant on the order. Use for cart-wide metadata such as a B2B PO number or marketing source. Max 250 pairs / 255-char keys; over the limit returns CARTATTRIBUTESLIMIT_EXCEEDED.

📄️ cartUpdateBuyerIdentity

Update buyer identity on the cart — email, phone, customer ID, country and language hints. Only supplied fields are touched; omit a field to leave it unchanged.

📄️ cartUpdateGiftCardRecipient

Set recipient details (email, display name, personalised message) on a gift card line item — the gift card will be delivered to this recipient on order completion.

📄️ cartUpdateLines

Update existing cart lines — quantity, custom attributes and / or configurator selections. Set quantity to 0 to remove a line. Address lines by CartLine.id.

📄️ cartUpdateNote

Set or replace the buyer note on the cart (free-form, up to 1000 chars). Surfaced to the merchant on the resulting order.

📄️ customerActivate

Activate customer account using raw activation token (admin-created flow)

📄️ customerAddAddress

Add customer address

📄️ customerLogin

Sign a customer in with email and password. Returns an access token to use on subsequent requests (as a Bearer header or via the SDK auth cookie).

📄️ customerLogout

Sign the current customer out. Invalidates the access token on the server; the SDK BFF auth helpers additionally clear the HTTP-only cookie.

📄️ customerRefreshToken

Exchange a still-valid access token for a fresh one with a later expiry. Call before expiresAt to keep the session alive without prompting the buyer to log in again.

📄️ customerRemoveAddress

Remove customer address

📄️ customerRequestPasswordReset

Request password reset email

📄️ customerResendVerificationEmail

Queue a fresh e-mail verification message for the currently authenticated customer. Returns ALREADY_VERIFIED when the address is verified. Rate-limited.

📄️ customerResetPassword

Reset customer password via signed URL from email

📄️ customerSetDefaultAddress

Set default address

📄️ customerSignup

Register a new customer with email and password. Returns the created customer plus an access token so the storefront can sign the buyer in immediately, no follow-up login call needed.

📄️ customerSubscribeToMarketing

Subscribe an email to the newsletter (guest-friendly, double opt-in).

📄️ customerUnsubscribeFromMarketing

Unsubscribe an email from the newsletter (guest-friendly, idempotent).

📄️ customerUpdateAddress

Update customer address

📄️ customerUpdate

Update customer profile

📄️ customerVerifyEmail

Confirm the e-mail address using the raw verification token from the verification e-mail. Single-use token (24h TTL); a repeated call after a successful verification returns success. Rate-limited.

📄️ digitalDownloadLinkCreate

Issues a single-use link for downloading purchased digital content. The link works once and then expires — do not cache it.

📄️ formSubmit

Submit a store-defined contact form. Values are validated against the form definition — errors come back in userErrors with stable codes and the offending field key in field. Bot-protection guarded and rate-limited.

📄️ loyaltyGenerateReferralCode

Generate or retrieve referral code

📄️ loyaltyRedeemReward

Redeem a loyalty reward

📄️ paymentCreate

Initiate a payment session for an order created by cartComplete. Call after checking order.canCreatePayment. Idempotent on the order — a second call returns the existing still-valid session. Branch on the returned payment.flow to launch the payment (redirect / embedded / instant). Rate-limited to 5 requests per minute per IP+shop.