Invoices

Module role in sales flow

invoices is the checkout state machine between cart and payment.

• create builds checkout state from current cart credentials.
• Address, shipping method, discount code, notes, and credit are all attached via invoice endpoints.
• payments depends on an existing invoice.

V2 contract notes

• get uses the refresh contract under the hood in v2 (POST /api/v2/invoices/{id}/refresh).
• create/refresh require a cart identifier from stored cart credentials.
• assignShippingMethod expects each invoiceItemIds value as a string.
• addCredit generally requires authenticated user context in Authorization.
• shippingAddress is normalized by SDK to remove duplicated/noisy fields.
• Invoice responses intentionally exclude user/userData profile objects.

Methods

Get

Use: invoices.get(options?).

Returns current invoice using stored cart + invoice credentials.

const invoiceRes = await client.invoices.get();

Create

Use: invoices.create(options?).

Creates invoice from current cart credentials.

await client.cart.addItem(12001, 1);
const invoiceRes = await client.invoices.create();

Refresh

Use: invoices.refresh(options?).

Syncs invoice with cart state.

await client.cart.addItem(12009, 1);
const refreshedInvoice = await client.invoices.refresh();

Add Shipping Address

Use: invoices.addShippingAddress(shippingAddressId, shippingAddressIdentifier, options?).

const addressRes = await client.shipping.createAddress({
  firstName: 'John',
  lastName: 'Doe',
  regionId: 1,
  cityId: 10,
  address: 'No. 10, Example St',
});

if (addressRes.data) {
  await client.invoices.addShippingAddress(
    addressRes.data.id,
    addressRes.data.identifier
  );
}

Add Discount Code

Use: invoices.addDiscountCode(code, options?).

Returns: SazitoResponse<Invoice>.

const res = await client.invoices.addDiscountCode('WELCOME10');
if (res.error) {
  // Invalid / expired code — show res.error.message to the user.
  console.warn(res.error.message); // e.g. "کد تخفیف معتبر نیست"
}

Error response. When the code is invalid or expired, the backend replies with a single field:

{ "message": "کد تخفیف معتبر نیست" }

The SDK surfaces it on res.error:

Assign Shipping Method

Use: invoices.assignShippingMethod(shippings, options?).

const shippingMethodsRes = await client.invoices.getApplicableShippingMethods();
const assignments = shippingMethodsRes.data?.itemsShippingRate.map((entry) => ({
  rateId: entry.shippingRate.id,
  invoiceItemIds: [entry.invoiceItemId],
})) ?? [];

if (assignments.length > 0) {
  await client.invoices.assignShippingMethod(assignments);
}

Add Details

Use: invoices.addDetails(comment, options?).

await client.invoices.addDetails('Please deliver between 14:00 and 16:00');

Add Form

Use: invoices.addForm(input, options?).

Attaches checkout dynamic form data to invoice via /api/v2/invoices/{id}/add_form. This is invoice-level checkout form data, not product form answers and not booking schedule fields.

await client.invoices.addForm({
  identifier: 'invoice-identifier-if-needed',
  formAttributes: {
    nationalCode: '0012345678',
    agreeToTerms: true,
  },
});

Get Applicable Shipping Methods

Use: invoices.getApplicableShippingMethods(options?).

Returns: SazitoResponse<ApplicableShippingMethods>.

const shippingRatesRes = await client.invoices.getApplicableShippingMethods();

Add Credit

Use: invoices.addCredit(options?).

Applies wallet credit to the current invoice. In most shops this flow requires authenticated user context.

await client.invoices.addCredit();

Remove Credit

Use: invoices.removeCredit(options?).

Removes wallet credit from the current invoice.

await client.invoices.removeCredit();

Toggle Credit

Use: invoices.toggleCredit(options?).

Toggles wallet credit based on current invoice.creditTotal.

await client.invoices.toggleCredit();

Clear Invoice

Use: invoices.clearInvoice().

Clears persisted invoice credentials only.

client.invoices.clearInvoice();

Invoice key fields

For user profile data, use users.getCurrentUser() instead of relying on invoice payloads.

Known errors

Examples

// app/lib/sazito-client.ts
import { createSazitoClient } from '@sazito/client-sdk';

export const sazito = createSazitoClient({
  domain: process.env.NEXT_PUBLIC_SAZITO_DOMAIN!,
});

// app/[lang]/(home)/page.tsx
'use client';
import { useEffect, useState } from 'react';
import { sazito } from '@/app/lib/sazito-client';

export default function Example() {
  const [data, setData] = useState<any>(null);

  useEffect(() => {
    (async () => {
      await sazito.cart.addItem(12001, 1);
      const res = await sazito.invoices.create();
      setData(res.data ?? null);
    })();
  }, []);

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Type Details

The following tables are generated from SDK TypeScript types and include nested object fields.

ShippingAssignment

Source: src/types/shipping.ts

ApplicableShippingMethods

Source: src/types/shipping.ts

Invoice

Source: src/types/invoice.ts

InvoiceItem

Source: src/types/invoice.ts

ShippingItem

Source: src/types/invoice.ts

ShippingAddress

Source: src/types/invoice.ts