Nouq Developers
API docs by Redocly

Nouq Storefront API (0.2.0)

Download OpenAPI specification:

The public API behind every Nouq storefront. Use it to build a headless storefront (your own frontend, app or integration) for any Nouq store.

  • Choose the store with the X-Nouq-Host header: <slug>.nouq.net or the store's own domain.
  • No API key, no cookies: everything here is public, and carts and orders are addressed by their unguessable token. CORS is open, so you can call it from the browser.
  • Money is an integer in minor units (halalas for SAR). Format it with Latin digits.
  • Errors are RFC 9457 problem details: code is for your code, detail is a shopper-friendly Arabic message, and fields has per-field messages.
  • SDKs: TypeScript (@nouq/storefront-sdk) and Go (github.com/nouq/nouq/backend/pkg/nouq). Start with the guide at nouq.net/developers.

storefront

storefrontCanonical

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
host
required
string
funnel_slug
string

This host is a funnel's domain: serve this sales page at / and send other paths to host

Response samples

Content type
application/json
{
  • "host": "string",
  • "funnel_slug": "string"
}

returnEligibility

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
allowed
required
boolean
why_not
required
string
deadline
required
string or null <date-time>
policy
required
string
exchanges
required
boolean
required
Array of objects
required
Array of objects (Return)

Response samples

Content type
application/json
{
  • "allowed": true,
  • "why_not": "string",
  • "deadline": "2019-08-24T14:15:22Z",
  • "policy": "string",
  • "exchanges": true,
  • "items": [
    • {
      }
    ],
  • "returns": [
    • {
      }
    ]
}

requestReturn

JSON, or multipart with a JSON "data" field and up to 3 "photos".

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema:
required
required
Array of objects
resolution
required
string (ReturnResolution)
Enum: "refund" "exchange"
reason
required
string (ReturnReason)
Enum: "wrong_size" "damaged" "not_as_described" "wrong_item" "changed_mind" "other"
note
string

Responses

Response Schema: application/json
id
required
string <uuid>
number
required
integer
order_id
required
string <uuid>
order_number
required
integer
status
required
string (ReturnStatus)
Enum: "requested" "approved" "rejected" "received" "refunded" "exchanged"
resolution
required
string (ReturnResolution)
Enum: "refund" "exchange"
reason
required
string (ReturnReason)
Enum: "wrong_size" "damaged" "not_as_described" "wrong_item" "changed_mind" "other"
note
required
string
photos
required
Array of strings
merchant_note
required
string
restocked
required
boolean
refund_amount
required
integer <int64>
refund_method
required
string

card | manual

suggested_refund
required
integer <int64>

Items' value after the order's discount

max_refund
required
integer <int64>

What's left to refund on the order

exchange_order_id
required
string or null <uuid>
price_difference
integer <int64>

Exchange only: positive = the shopper pays it, negative = refunded to them

payment_method
required
string
customer_name
required
string
customer_phone
required
string
currency
required
string
required
Array of objects (ReturnItem)
created_at
required
string <date-time>
updated_at
required
string <date-time>

Request samples

Content type
{
  • "items": [
    • {
      }
    ],
  • "resolution": "refund",
  • "reason": "wrong_size",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": 0,
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "order_number": 0,
  • "status": "requested",
  • "resolution": "refund",
  • "reason": "wrong_size",
  • "note": "string",
  • "photos": [
    • "string"
    ],
  • "merchant_note": "string",
  • "restocked": true,
  • "refund_amount": 0,
  • "refund_method": "string",
  • "suggested_refund": 0,
  • "max_refund": 0,
  • "exchange_order_id": "fada7d0f-ca50-498f-8ea8-24ba1cc005e1",
  • "price_difference": 0,
  • "payment_method": "string",
  • "customer_name": "string",
  • "customer_phone": "string",
  • "currency": "string",
  • "items": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

reviewForm

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
allowed
required
boolean
why
required
string

Shopper-facing reason when not allowed

name
required
string

Suggested display name (first name and initial)

required
Array of objects

Response samples

Content type
application/json
{
  • "allowed": true,
  • "why": "string",
  • "name": "string",
  • "items": [
    • {
      }
    ]
}

submitReviews

Verified buyers only (delivered order), one review per product. JSON, or multipart with a JSON "data" field and up to 4 photos per product in "photos_".

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema:
required
name
string

Display name; empty uses the suggested one

required
Array of objects

Responses

Response Schema: application/json
Array
id
required
string <uuid>
author_name
required
string
rating
required
integer [ 1 .. 5 ]
body
required
string
photos
required
Array of strings
verified
required
boolean

Written from a delivered order

reply
required
string

The store's public answer

replied_at
required
string or null <date-time>
created_at
required
string <date-time>

Request samples

Content type
{
  • "name": "string",
  • "reviews": [
    • {
      }
    ]
}

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "author_name": "string",
    • "rating": 1,
    • "body": "string",
    • "photos": [
      ],
    • "verified": true,
    • "reply": "string",
    • "replied_at": "2019-08-24T14:15:22Z",
    • "created_at": "2019-08-24T14:15:22Z"
    }
]

storeReviews

query Parameters
min_rating
integer [ 1 .. 5 ]
Default: 4

Only reviews with at least this many stars

limit
integer [ 1 .. 12 ]
Default: 6
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
count
required
integer

Every published review in the store

average
required
number
required
Array of objects

Response samples

Content type
application/json
{
  • "count": 0,
  • "average": 0,
  • "items": [
    • {
      }
    ]
}

productReviews

path Parameters
slug
required
string
query Parameters
page
integer >= 1
per_page
integer [ 1 .. 100 ]
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
object (RatingSummary)
required
Array of objects (PublicReview)
page
required
integer
per_page
required
integer

Response samples

Content type
application/json
{
  • "summary": {
    • "count": 0,
    • "average": 0,
    • "distribution": [
      ]
    },
  • "items": [
    • {
      }
    ],
  • "page": 0,
  • "per_page": 0
}

unsubscribe

Withdraw marketing consent using the signed link from a message.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

storefrontTheme

query Parameters
preview
string

Preview token: returns the draft instead of the published theme

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
ThemeDocument (object) or null
required
object (Occasions)
preview
required
boolean
package_css
string

Scoped CSS of a marketplace template the store is entitled to

Response samples

Content type
application/json
{
  • "document": { },
  • "occasions": {
    • "auto": true,
    • "disabled": [
      ],
    • "forced": "string"
    },
  • "preview": true,
  • "package_css": "string"
}

storefrontLanding

path Parameters
slug
required
string
query Parameters
preview
string

A draft's preview token

bucket
integer [ 0 .. 99 ]

The visitor's A/B bucket: under a test, the page's other version may come back, under its own slug

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
slug
required
string
style
required
string
Enum: "bold" "clean" "story"
required
object (LandingContent)
required
Array of objects (LandingOffer)
required
Array of objects (LandingPublicAddon)
product_slug
required
string
preview
required
boolean

A draft opened with its preview token

live
required
boolean

False while the funnel is paused or outside its schedule: send the visitor to the product page (nothing else is filled in)

required
object

The product's real sales, for the sold and stock blocks (zero when the page shows neither)

funnel_host
required
string

The funnel's own live domain, which serves this page at / (its canonical address); empty when it has none

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "style": "bold",
  • "content": {
    • "badge": "string",
    • "headline": "string",
    • "subheadline": "string",
    • "images": [
      ],
    • "video_url": "string",
    • "benefits": [
      ],
    • "features": [
      ],
    • "show_reviews": true,
    • "review_images": [
      ],
    • "faq": [
      ],
    • "guarantees": [
      ],
    • "cta": "string",
    • "ends_at": "2019-08-24T14:15:22Z",
    • "show_stock": true,
    • "whatsapp_order": true,
    • "blocks": [
      ],
    • "layout": {
      },
    • "form": {
      }
    },
  • "offers": [
    • {
      }
    ],
  • "addons": [
    • {
      }
    ],
  • "product_slug": "string",
  • "preview": true,
  • "live": true,
  • "proof": {
    • "sold_week": 0,
    • "sold_month": 0
    },
  • "funnel_host": "string"
}

storefrontLandingView

Counts one visit (send once per session). Drafts and unknown pages are ignored.

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

storefrontLandingFormStart

Counts a visitor starting the order form (send once per browser per day). Drafts and unknown pages are ignored.

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

storefrontLandingCart

Replaces the landing cart's lines with the shopper's pick (this product only) and prices the page's quantity offer.

path Parameters
slug
required
string
query Parameters
preview
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
cart_token
string

The landing cart to replace; empty starts one

required
Array of objects

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "cart_token": "string",
  • "lines": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

storefrontFunnelThankYou

The thank-you message of the funnel a landing page (an order's landing_page_id) belongs to.

path Parameters
id
required
string <uuid>
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
headline
required
string <= 120 characters

Empty: the store's thank-you

body
required
string <= 600 characters

Response samples

Content type
application/json
{
  • "headline": "string",
  • "body": "string"
}

storefrontLandingTemplate

A funnel template rendered for one of the store's active products, as a preview page (nothing saved, preview true).

path Parameters
id
required
string
query Parameters
product
string

An active product's slug (default: the store's first active product)

lang
string
Enum: "ar" "en"
package_token
string

A designer package's preview token: its latest unapproved version

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
slug
required
string
style
required
string
Enum: "bold" "clean" "story"
required
object (LandingContent)
required
Array of objects (LandingOffer)
required
Array of objects (LandingPublicAddon)
product_slug
required
string
preview
required
boolean

A draft opened with its preview token

live
required
boolean

False while the funnel is paused or outside its schedule: send the visitor to the product page (nothing else is filled in)

required
object

The product's real sales, for the sold and stock blocks (zero when the page shows neither)

funnel_host
required
string

The funnel's own live domain, which serves this page at / (its canonical address); empty when it has none

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "style": "bold",
  • "content": {
    • "badge": "string",
    • "headline": "string",
    • "subheadline": "string",
    • "images": [
      ],
    • "video_url": "string",
    • "benefits": [
      ],
    • "features": [
      ],
    • "show_reviews": true,
    • "review_images": [
      ],
    • "faq": [
      ],
    • "guarantees": [
      ],
    • "cta": "string",
    • "ends_at": "2019-08-24T14:15:22Z",
    • "show_stock": true,
    • "whatsapp_order": true,
    • "blocks": [
      ],
    • "layout": {
      },
    • "form": {
      }
    },
  • "offers": [
    • {
      }
    ],
  • "addons": [
    • {
      }
    ],
  • "product_slug": "string",
  • "preview": true,
  • "live": true,
  • "proof": {
    • "sold_week": 0,
    • "sold_month": 0
    },
  • "funnel_host": "string"
}

storefrontPages

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
slug
required
string
title
required
string
body
required
string

Markdown subset

kind
required
string (PageKind)
Enum: "custom" "about" "contact" "privacy" "returns" "shipping" "terms"
published
required
boolean
required
object (SEO)
updated_at
required
string <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "slug": "string",
    • "title": "string",
    • "body": "string",
    • "kind": "custom",
    • "published": true,
    • "seo": {
      },
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]

storefrontPage

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
slug
required
string
title
required
string
body
required
string

Markdown subset

kind
required
string (PageKind)
Enum: "custom" "about" "contact" "privacy" "returns" "shipping" "terms"
published
required
boolean
required
object (SEO)
updated_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title": "string",
  • "body": "string",
  • "kind": "custom",
  • "published": true,
  • "seo": {
    • "title": "string",
    • "description": "string",
    • "image": "string"
    },
  • "updated_at": "2019-08-24T14:15:22Z"
}

storefrontPosts

query Parameters
category
string
page
integer >= 1
per_page
integer [ 1 .. 100 ]
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
Array of objects (BlogPost)
total
required
integer
page
required
integer
per_page
required
integer
required
Array of objects

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "total": 0,
  • "page": 0,
  • "per_page": 0,
  • "categories": [
    • {
      }
    ]
}

storefrontPost

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
slug
required
string
title
required
string
excerpt
required
string
body
required
string
cover_url
required
string
category
required
string
author
required
string
status
required
string
Enum: "draft" "published"
published_at
required
string or null <date-time>
required
object (SEO)
updated_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title": "string",
  • "excerpt": "string",
  • "body": "string",
  • "cover_url": "string",
  • "category": "string",
  • "author": "string",
  • "status": "draft",
  • "published_at": "2019-08-24T14:15:22Z",
  • "seo": {
    • "title": "string",
    • "description": "string",
    • "image": "string"
    },
  • "updated_at": "2019-08-24T14:15:22Z"
}

subscribeNewsletter

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
contact
required
string

Email or Saudi mobile number

consent
required
boolean

Responses

Request samples

Content type
application/json
{
  • "contact": "string",
  • "consent": true
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

storefrontPopups

The popups running now with their rules; the browser picks at most one per page view.

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
kind
required
string
Enum: "signup" "announcement"
required
object (PopupContent)
required
object (PopupDesign)
required
object (PopupTrigger)
required
object (PopupTargeting)
required
object (PopupFrequency)
has_reward
required
boolean
priority
required
integer
ends_at
required
string or null <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "kind": "signup",
    • "content": {
      },
    • "design": {
      },
    • "trigger": {
      },
    • "targeting": {
      },
    • "frequency": {
      },
    • "has_reward": true,
    • "priority": 0,
    • "ends_at": "2019-08-24T14:15:22Z"
    }
]

submitPopup

Signs a shopper up with marketing consent and returns their single-use code (also sent on WhatsApp).

path Parameters
id
required
string <uuid>
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
contact
required
string

A Saudi mobile number or an email

consent
required
boolean
locale
string
Enum: "ar" "en"
website
string

Honeypot: leave empty

Responses

Response Schema: application/json
code
required
string

The single-use code (empty when the popup gives none)

already
required
boolean

This contact signed up before; code is the one they got then

Request samples

Content type
application/json
{
  • "contact": "string",
  • "consent": true,
  • "locale": "ar",
  • "website": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "already": true
}

popupEvent

path Parameters
id
required
string <uuid>
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
type
required
string
Enum: "view" "close"

Responses

Request samples

Content type
application/json
{
  • "type": "view"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

getCurrentStore

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
phone_messages
required
boolean

Nouq can deliver WhatsApp and SMS (PHONE_CODES). False: shoppers hear by email only; don't offer or promise phone messages

id
required
string <uuid>
slug
required
string
name
required
string
description
required
string
logo_url
required
string
whatsapp_phone
required
string
currency
required
string
locale
required
string (Locale)
Enum: "ar" "en"
status
required
string
Enum: "active" "suspended" "closed"
cod_enabled
required
boolean
cod_fee
required
integer <int64> (Money)

Minor units (halalas)

vat_enabled
required
boolean
vat_rate_bp
required
integer
min_order_total
required
integer <int64> (Money)

The least the store takes an order for: products after offers and discounts, before rewards and shipping (0: no minimum)

recovery_enabled
required
boolean
recovery_delay_minutes
required
integer
recovery_discount_code
required
string
required
Array of objects (Domain)
created_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "phone_messages": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "name": "string",
  • "description": "string",
  • "logo_url": "string",
  • "whatsapp_phone": "string",
  • "currency": "string",
  • "locale": "ar",
  • "status": "active",
  • "cod_enabled": true,
  • "cod_fee": 0,
  • "vat_enabled": true,
  • "vat_rate_bp": 0,
  • "min_order_total": 0,
  • "recovery_enabled": true,
  • "recovery_delay_minutes": 0,
  • "recovery_discount_code": "string",
  • "domains": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

storefrontCategories

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
slug
required
string
name_ar
required
string
name_en
required
string
position
required
integer
product_count
required
integer
description_ar
required
string

Intro text shown above the category's products

description_en
required
string
required
object (SearchSnippet)

What a product or category shows in Google. Empty fields fall back to the title and description.

updated_at
required
string <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "slug": "string",
    • "name_ar": "string",
    • "name_en": "string",
    • "position": 0,
    • "product_count": 0,
    • "description_ar": "string",
    • "description_en": "string",
    • "seo": {
      },
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]

storefrontProducts

query Parameters
category
string
featured
string
Value: "true"
q
string
page
integer >= 1
per_page
integer [ 1 .. 100 ]
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
Array of objects (ProductSummary)
total
required
integer
page
required
integer
per_page
required
integer

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "total": 0,
  • "page": 0,
  • "per_page": 0
}

storefrontProduct

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
slug
required
string
title_ar
required
string
title_en
required
string
description_ar
required
string
description_en
required
string
status
required
string
Enum: "draft" "active" "archived"
featured
required
boolean
required
Array of objects (Option)
required
Array of objects (Variant)
images
required
Array of strings
category_ids
required
Array of strings <uuid> [ items <uuid > ]
required
object (SearchSnippet)

What a product or category shows in Google. Empty fields fall back to the title and description.

free_shipping
required
boolean

This product ships free. An order ships free when every line in it does

required
object (ProductPageSettings)

How this product's page sells, for products sold from an ad. All off: the store's normal product page.

created_at
required
string <date-time>
updated_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "slug": "string",
  • "title_ar": "string",
  • "title_en": "string",
  • "description_ar": "string",
  • "description_en": "string",
  • "status": "draft",
  • "featured": true,
  • "options": [
    • {
      }
    ],
  • "variants": [
    • {
      }
    ],
  • "images": [
    • "string"
    ],
  • "category_ids": [
    • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
  • "seo": {
    • "title": "string",
    • "description": "string"
    },
  • "free_shipping": true,
  • "page": {
    • "buy_now": true,
    • "button_label": "string",
    • "order_form": "",
    • "hide_chrome": true,
    • "hide_related": true,
    • "sticky_bar": "",
    • "hide_reviews": true
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

storefrontShippingMethods

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
name_ar
required
string
name_en
required
string
eta_ar
required
string
eta_en
required
string
price
required
integer <int64> (Money)

Minor units (halalas)

required
Money (integer) or null
active
required
boolean
position
required
integer
carrier
string

'' = flat price; otherwise priced live by this carrier

markup
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (RegionPrice)
other_regions
required
string (OtherRegions)
Enum: "base" "none"

What regions without their own price get: base = the method's price, none = no delivery

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name_ar": "string",
    • "name_en": "string",
    • "eta_ar": "string",
    • "eta_en": "string",
    • "price": 0,
    • "free_over": 0,
    • "active": true,
    • "position": 0,
    • "carrier": "string",
    • "markup": 0,
    • "region_prices": [
      ],
    • "other_regions": "base"
    }
]

storefrontGovernorates

Egypt's governorates, for an Egyptian store's address form (the governorate goes in the address's city).

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
code
required
string
name_ar
required
string
name_en
required
string
region
required
string
Enum: "greater_cairo" "alex_delta" "upper_canal" "remote"

Response samples

Content type
application/json
[
  • {
    • "code": "string",
    • "name_ar": "string",
    • "name_en": "string",
    • "region": "greater_cairo"
    }
]

createCart

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

getCart

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

addCartItem

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
variant_id
required
string <uuid>
quantity
required
integer >= 1

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
  • "quantity": 1
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

setCartItemQuantity

path Parameters
token
required
string
variantID
required
string <uuid>
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
quantity
required
integer >= 0

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "quantity": 0
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

applyCoupon

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
code
required
string

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

removeCoupon

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

setCartContact

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
phone
required
string
name
string
marketing_consent
boolean

Reminders are only sent with consent

Responses

Request samples

Content type
application/json
{
  • "phone": "string",
  • "name": "string",
  • "marketing_consent": true
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

checkout

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
card_prefix
string^[0-9]{6}$

First 6 digits of the card, for a bank's card offer. Never more of the card than this

cart_token
required
string
required
object (Customer)
required
object (Address)
shipping_method_id
required
string <uuid>
payment_method
required
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

note
string
marketing_consent
boolean

Explicit opt-in to offers and reminders (PDPL); never pre-ticked

object (CheckoutTracking)

Attribution and ad consent for a checkout; written with the order.

passport_token
string

The store's Passport link token, when the shopper used Passport

account_token
string

The shopper's session on the store's own account (ADR 0023), when signed in

object

Answers to the store's checkout questions, by question key

object

What the store's own order form saw, for the silent bot check. Other clients leave it out. A filled trap refuses the order.

challenge_token
string

The Cloudflare Turnstile token, after checkout answered 422 with fields.challenge (the widget's site key)

phone_whatsapp
boolean

The shopper's answer to "is this number on WhatsApp?" (a funnel's form can ask); leave out when not asked

Responses

Response Schema: application/json
id
required
string <uuid>
number
required
integer
token
required
string
status
required
string (OrderStatus)
Enum: "pending_confirmation" "pending_payment" "confirmed" "processing" "shipped" "delivered" "cancelled"
payment_method
required
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

payment_status
required
string
Enum: "unpaid" "deposit_paid" "paid" "refunded"
currency
required
string
subtotal
required
integer <int64> (Money)

Minor units (halalas)

shipping_total
required
integer <int64> (Money)

Minor units (halalas)

cod_fee
required
integer <int64> (Money)

Minor units (halalas)

discount_total
required
integer <int64> (Money)

Minor units (halalas)

discount_code
required
string
recovered_from_cart
required
boolean
vat_total
required
integer <int64> (Money)

Minor units (halalas)

total
required
integer <int64> (Money)

Minor units (halalas)

refunded_total
required
integer <int64> (Money)

Minor units (halalas)

deposit_amount
required
integer <int64> (Money)

Partial COD: paid online before shipping; the rest on delivery

via_passport
required
boolean

Placed with a Nouq Passport (verified phone)

loyalty_points
required
integer

Points spent on the order

loyalty_amount
required
integer <int64> (Money)

What the points took off (also in discount_total)

referral_amount
required
integer <int64> (Money)

Friend-referral discount (also in discount_total)

offer_total
required
integer <int64> (Money)

A landing page's quantity offer (also in discount_total)

upsell_total
required
integer <int64> (Money)

What cross-sell and post-purchase offers took off (also in discount_total)

landing_page_id
required
string or null <uuid>

The landing page the order came from

phone_whatsapp
required
boolean or null

Whether the shopper said their number is on WhatsApp (null: not asked)

parent_order_id
required
string or null <uuid>

The order this one ships with: an after-order offer accepted on a paid card order becomes its own small order, paid on its own

required
object (Customer)
required
object (Address)
shipping_method
required
string
note
required
string
required
Array of objects (FieldAnswer)

Answers to the store's checkout questions

payment_discount
required
integer <int64> (Money)

What paying this way took off (also in discount_total)

bank_offer
required
string

The bank whose card offer the order took (its amount is in payment_discount)

card_prefix
required
string

First 6 digits the shopper gave for that offer

paid_card_prefix
required
string

First 6 digits of the card the gateway reports paid (empty: not reported yet)

bank_offer_mismatch
required
boolean

The card that paid isn't in the offer

cod_confirmed_at
required
string or null <date-time>
cod_reminders
required
integer

Confirmation reminders sent (COD)

cod_expires_at
required
string or null <date-time>

When an unconfirmed COD order cancels itself

address_confirmed_at
required
string or null <date-time>
delivery_window
required
string
Enum: "" "morning" "afternoon" "evening"
required
Array of objects (OrderItem)
required
Array of objects (Shipment)
created_at
required
string <date-time>
updated_at
required
string <date-time>
Array of objects (OrderEvent)

Merchant view only

next_actions
Array of strings (OrderStatus)
Items Enum: "pending_confirmation" "pending_payment" "confirmed" "processing" "shipped" "delivered" "cancelled"

Merchant view only

Request samples

Content type
application/json
{
  • "card_prefix": "string",
  • "cart_token": "string",
  • "customer": {
    • "name": "string",
    • "phone": "string",
    • "email": "string"
    },
  • "address": {
    • "city": "string",
    • "district": "string",
    • "street": "string",
    • "building_number": "string",
    • "additional_number": "string",
    • "postal_code": "string",
    • "short_address": "string",
    • "floor": "string",
    • "apartment": "string",
    • "landmark": "string",
    • "lat": 0,
    • "lng": 0,
    • "notes": "string"
    },
  • "shipping_method_id": "b81aac29-0c95-49e2-9c74-882116d2f822",
  • "payment_method": "cod",
  • "note": "string",
  • "marketing_consent": true,
  • "tracking": {
    • "visitor_id": "1b5d452e-2897-4f21-ac74-1b59f820ba97",
    • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
    • "touch": {
      },
    • "consent": "string",
    • "host": "string",
    • "client": {
      }
    },
  • "passport_token": "string",
  • "account_token": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    },
  • "bot": {
    • "trap": "string",
    • "form_ms": 0
    },
  • "challenge_token": "string",
  • "phone_whatsapp": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": 0,
  • "token": "string",
  • "status": "pending_confirmation",
  • "payment_method": "cod",
  • "payment_status": "unpaid",
  • "currency": "string",
  • "subtotal": 0,
  • "shipping_total": 0,
  • "cod_fee": 0,
  • "discount_total": 0,
  • "discount_code": "string",
  • "recovered_from_cart": true,
  • "vat_total": 0,
  • "total": 0,
  • "refunded_total": 0,
  • "deposit_amount": 0,
  • "via_passport": true,
  • "loyalty_points": 0,
  • "loyalty_amount": 0,
  • "referral_amount": 0,
  • "offer_total": 0,
  • "upsell_total": 0,
  • "landing_page_id": "414a5bce-f320-4a62-9fa5-1a44e5cc334f",
  • "phone_whatsapp": true,
  • "parent_order_id": "aca22822-0c4a-4277-bcc3-199a8417c244",
  • "customer": {
    • "name": "string",
    • "phone": "string",
    • "email": "string"
    },
  • "address": {
    • "city": "string",
    • "district": "string",
    • "street": "string",
    • "building_number": "string",
    • "additional_number": "string",
    • "postal_code": "string",
    • "short_address": "string",
    • "floor": "string",
    • "apartment": "string",
    • "landmark": "string",
    • "lat": 0,
    • "lng": 0,
    • "notes": "string"
    },
  • "shipping_method": "string",
  • "note": "string",
  • "custom_fields": [
    • {
      }
    ],
  • "payment_discount": 0,
  • "bank_offer": "string",
  • "card_prefix": "string",
  • "paid_card_prefix": "string",
  • "bank_offer_mismatch": true,
  • "cod_confirmed_at": "2019-08-24T14:15:22Z",
  • "cod_reminders": 0,
  • "cod_expires_at": "2019-08-24T14:15:22Z",
  • "address_confirmed_at": "2019-08-24T14:15:22Z",
  • "delivery_window": "",
  • "items": [
    • {
      }
    ],
  • "shipments": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "events": [
    • {
      }
    ],
  • "next_actions": [
    • "pending_confirmation"
    ]
}

storefrontOrder

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
number
required
integer
token
required
string
status
required
string (OrderStatus)
Enum: "pending_confirmation" "pending_payment" "confirmed" "processing" "shipped" "delivered" "cancelled"
payment_method
required
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

payment_status
required
string
Enum: "unpaid" "deposit_paid" "paid" "refunded"
currency
required
string
subtotal
required
integer <int64> (Money)

Minor units (halalas)

shipping_total
required
integer <int64> (Money)

Minor units (halalas)

cod_fee
required
integer <int64> (Money)

Minor units (halalas)

discount_total
required
integer <int64> (Money)

Minor units (halalas)

discount_code
required
string
recovered_from_cart
required
boolean
vat_total
required
integer <int64> (Money)

Minor units (halalas)

total
required
integer <int64> (Money)

Minor units (halalas)

refunded_total
required
integer <int64> (Money)

Minor units (halalas)

deposit_amount
required
integer <int64> (Money)

Partial COD: paid online before shipping; the rest on delivery

via_passport
required
boolean

Placed with a Nouq Passport (verified phone)

loyalty_points
required
integer

Points spent on the order

loyalty_amount
required
integer <int64> (Money)

What the points took off (also in discount_total)

referral_amount
required
integer <int64> (Money)

Friend-referral discount (also in discount_total)

offer_total
required
integer <int64> (Money)

A landing page's quantity offer (also in discount_total)

upsell_total
required
integer <int64> (Money)

What cross-sell and post-purchase offers took off (also in discount_total)

landing_page_id
required
string or null <uuid>

The landing page the order came from

phone_whatsapp
required
boolean or null

Whether the shopper said their number is on WhatsApp (null: not asked)

parent_order_id
required
string or null <uuid>

The order this one ships with: an after-order offer accepted on a paid card order becomes its own small order, paid on its own

required
object (Customer)
required
object (Address)
shipping_method
required
string
note
required
string
required
Array of objects (FieldAnswer)

Answers to the store's checkout questions

payment_discount
required
integer <int64> (Money)

What paying this way took off (also in discount_total)

bank_offer
required
string

The bank whose card offer the order took (its amount is in payment_discount)

card_prefix
required
string

First 6 digits the shopper gave for that offer

paid_card_prefix
required
string

First 6 digits of the card the gateway reports paid (empty: not reported yet)

bank_offer_mismatch
required
boolean

The card that paid isn't in the offer

cod_confirmed_at
required
string or null <date-time>
cod_reminders
required
integer

Confirmation reminders sent (COD)

cod_expires_at
required
string or null <date-time>

When an unconfirmed COD order cancels itself

address_confirmed_at
required
string or null <date-time>
delivery_window
required
string
Enum: "" "morning" "afternoon" "evening"
required
Array of objects (OrderItem)
required
Array of objects (Shipment)
created_at
required
string <date-time>
updated_at
required
string <date-time>
Array of objects (OrderEvent)

Merchant view only

next_actions
Array of strings (OrderStatus)
Items Enum: "pending_confirmation" "pending_payment" "confirmed" "processing" "shipped" "delivered" "cancelled"

Merchant view only

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": 0,
  • "token": "string",
  • "status": "pending_confirmation",
  • "payment_method": "cod",
  • "payment_status": "unpaid",
  • "currency": "string",
  • "subtotal": 0,
  • "shipping_total": 0,
  • "cod_fee": 0,
  • "discount_total": 0,
  • "discount_code": "string",
  • "recovered_from_cart": true,
  • "vat_total": 0,
  • "total": 0,
  • "refunded_total": 0,
  • "deposit_amount": 0,
  • "via_passport": true,
  • "loyalty_points": 0,
  • "loyalty_amount": 0,
  • "referral_amount": 0,
  • "offer_total": 0,
  • "upsell_total": 0,
  • "landing_page_id": "414a5bce-f320-4a62-9fa5-1a44e5cc334f",
  • "phone_whatsapp": true,
  • "parent_order_id": "aca22822-0c4a-4277-bcc3-199a8417c244",
  • "customer": {
    • "name": "string",
    • "phone": "string",
    • "email": "string"
    },
  • "address": {
    • "city": "string",
    • "district": "string",
    • "street": "string",
    • "building_number": "string",
    • "additional_number": "string",
    • "postal_code": "string",
    • "short_address": "string",
    • "floor": "string",
    • "apartment": "string",
    • "landmark": "string",
    • "lat": 0,
    • "lng": 0,
    • "notes": "string"
    },
  • "shipping_method": "string",
  • "note": "string",
  • "custom_fields": [
    • {
      }
    ],
  • "payment_discount": 0,
  • "bank_offer": "string",
  • "card_prefix": "string",
  • "paid_card_prefix": "string",
  • "bank_offer_mismatch": true,
  • "cod_confirmed_at": "2019-08-24T14:15:22Z",
  • "cod_reminders": 0,
  • "cod_expires_at": "2019-08-24T14:15:22Z",
  • "address_confirmed_at": "2019-08-24T14:15:22Z",
  • "delivery_window": "",
  • "items": [
    • {
      }
    ],
  • "shipments": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "events": [
    • {
      }
    ],
  • "next_actions": [
    • "pending_confirmation"
    ]
}

storefrontQuantityOffer

The product's active quantity tiers, for its page.

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
QuantityOffer (object) or null

Response samples

Content type
application/json
{
  • "offer": {
    • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
    • "headline": "string",
    • "tiers": [
      ]
    }
}

storefrontProductBundles

The active bundles naming this product that can be bought now.

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
offer_id
required
string <uuid>
kind
required
string
Enum: "fixed" "box"
headline
required
string
price
required
integer <int64> (Money)

Minor units (halalas)

quantity
required
integer

box: pieces to pick

regular
required
integer <int64> (Money)

What the pieces cost without the bundle (box: filled with the dearest, the most it can save)

required
Array of objects

Response samples

Content type
application/json
[
  • {
    • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
    • "kind": "fixed",
    • "headline": "string",
    • "price": 0,
    • "quantity": 0,
    • "regular": 0,
    • "products": [
      ]
    }
]

storefrontProductRecommendations

Real co-purchases for the product's page.

path Parameters
slug
required
string
query Parameters
limit
integer [ 1 .. 12 ]
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
Array of objects (ProductSummary)

Bought in the same order at least twice in the last year, most often first; in stock

required
Array of objects (ProductSummary)

Co-purchases, then the same category, then featured products

Response samples

Content type
application/json
{
  • "frequently_bought": [
    • {
      }
    ],
  • "also_like": [
    • {
      }
    ]
}

storefrontCartRecommendations

Real co-purchases of what's in the cart.

path Parameters
token
required
string
query Parameters
limit
integer [ 1 .. 12 ]
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
Array of objects (ProductSummary)

Bought in the same order at least twice in the last year, most often first; in stock

required
Array of objects (ProductSummary)

Co-purchases, then the same category, then featured products

Response samples

Content type
application/json
{
  • "frequently_bought": [
    • {
      }
    ],
  • "also_like": [
    • {
      }
    ]
}

storefrontOrderFormCart

Sets the cart behind the order form on a product page: separate from the shopper's normal cart, priced like a store cart.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
cart_token
string

The landing cart to replace; empty starts one

required
Array of objects

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "cart_token": "string",
  • "lines": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

storefrontOrderUpsell

The post-purchase offer (recorded as shown): for a COD order awaiting confirmation (accepting adds to it), or a paid card order not shipped yet (accepting makes a small order of its own to pay, shipped with it).

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
PostPurchaseOffer (object) or null

Response samples

Content type
application/json
{
  • "offer": {
    • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
    • "stage": "upsell",
    • "headline": "string",
    • "product_slug": "string",
    • "title_ar": "string",
    • "title_en": "string",
    • "image_url": "string",
    • "discount_percent": 0,
    • "variants": [
      ],
    • "expires_at": "2019-08-24T14:15:22Z"
    }
}

answerOrderUpsell

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
offer_id
required
string <uuid>
stage
required
string (UpsellStage)
Enum: "upsell" "downsell"
accept
required
boolean
variant_id
string or null <uuid>

Required when accepting

Responses

Response Schema: application/json
required
object (Order)
required
PostPurchaseOffer (object) or null

Request samples

Content type
application/json
{
  • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
  • "stage": "upsell",
  • "accept": true,
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6"
}

Response samples

Content type
application/json
{
  • "order": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "number": 0,
    • "token": "string",
    • "status": "pending_confirmation",
    • "payment_method": "cod",
    • "payment_status": "unpaid",
    • "currency": "string",
    • "subtotal": 0,
    • "shipping_total": 0,
    • "cod_fee": 0,
    • "discount_total": 0,
    • "discount_code": "string",
    • "recovered_from_cart": true,
    • "vat_total": 0,
    • "total": 0,
    • "refunded_total": 0,
    • "deposit_amount": 0,
    • "via_passport": true,
    • "loyalty_points": 0,
    • "loyalty_amount": 0,
    • "referral_amount": 0,
    • "offer_total": 0,
    • "upsell_total": 0,
    • "landing_page_id": "414a5bce-f320-4a62-9fa5-1a44e5cc334f",
    • "phone_whatsapp": true,
    • "parent_order_id": "aca22822-0c4a-4277-bcc3-199a8417c244",
    • "customer": {
      },
    • "address": {
      },
    • "shipping_method": "string",
    • "note": "string",
    • "custom_fields": [
      ],
    • "payment_discount": 0,
    • "bank_offer": "string",
    • "card_prefix": "string",
    • "paid_card_prefix": "string",
    • "bank_offer_mismatch": true,
    • "cod_confirmed_at": "2019-08-24T14:15:22Z",
    • "cod_reminders": 0,
    • "cod_expires_at": "2019-08-24T14:15:22Z",
    • "address_confirmed_at": "2019-08-24T14:15:22Z",
    • "delivery_window": "",
    • "items": [
      ],
    • "shipments": [
      ],
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z",
    • "events": [
      ],
    • "next_actions": [
      ]
    },
  • "next": {
    • "offer_id": "d5a7a5b7-a4a3-49e7-9c69-b44d2cbe15cf",
    • "stage": "upsell",
    • "headline": "string",
    • "product_slug": "string",
    • "title_ar": "string",
    • "title_en": "string",
    • "image_url": "string",
    • "discount_percent": 0,
    • "variants": [
      ],
    • "expires_at": "2019-08-24T14:15:22Z"
    }
}

storefrontOrderInvoices

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
order_id
required
string or null <uuid>
kind
required
string (InvoiceKind)
Enum: "invoice" "credit_note"
number
required
string
uuid
required
string <uuid>
icv
required
integer <int64>
signed
required
boolean

false for Phase-1 documents (store not onboarded with ZATCA)

currency
required
string
taxable_total
required
integer <int64>
vat_total
required
integer <int64>
total
required
integer <int64>
vat_rate_bp
required
integer
issued_at
required
string <date-time>
reason
required
string
billing_ref
required
string

Credit notes: the original invoice number

required
object (InvoiceSeller)
buyer_name
required
string
standard
required
boolean

A standard (B2B) tax invoice, cleared by ZATCA

required
InvoiceBuyer (object) or null

The business the document was issued to

required
object (InvoiceTotals)

Tax-exclusive figures exactly as in the document's XML (minor units).

qr
required
string

Base64 TLV payload the QR code encodes

zatca_status
required
string (InvoiceZatcaStatus)
Enum: "unsigned" "pending" "reported" "cleared" "warning" "rejected" "local"

cleared: a standard (B2B) document cleared by ZATCA; local: an Egyptian store's invoice, which never goes to ZATCA

required
Array of objects
reported_at
required
string or null <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    • "kind": "invoice",
    • "number": "INV-1001",
    • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    • "icv": 0,
    • "signed": true,
    • "currency": "string",
    • "taxable_total": 0,
    • "vat_total": 0,
    • "total": 0,
    • "vat_rate_bp": 0,
    • "issued_at": "2019-08-24T14:15:22Z",
    • "reason": "string",
    • "billing_ref": "string",
    • "seller": {
      },
    • "buyer_name": "string",
    • "standard": true,
    • "buyer": {
      },
    • "totals": {
      },
    • "qr": "string",
    • "zatca_status": "unsigned",
    • "zatca_messages": [
      ],
    • "reported_at": "2019-08-24T14:15:22Z"
    }
]

answerCOD

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
confirm
required
boolean
object (AddressConfirmation)

What the shopper confirms about delivery when confirming a COD order; empty fields keep checkout's.

Responses

Response Schema: application/json
id
required
string <uuid>
number
required
integer
token
required
string
status
required
string (OrderStatus)
Enum: "pending_confirmation" "pending_payment" "confirmed" "processing" "shipped" "delivered" "cancelled"
payment_method
required
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

payment_status
required
string
Enum: "unpaid" "deposit_paid" "paid" "refunded"
currency
required
string
subtotal
required
integer <int64> (Money)

Minor units (halalas)

shipping_total
required
integer <int64> (Money)

Minor units (halalas)

cod_fee
required
integer <int64> (Money)

Minor units (halalas)

discount_total
required
integer <int64> (Money)

Minor units (halalas)

discount_code
required
string
recovered_from_cart
required
boolean
vat_total
required
integer <int64> (Money)

Minor units (halalas)

total
required
integer <int64> (Money)

Minor units (halalas)

refunded_total
required
integer <int64> (Money)

Minor units (halalas)

deposit_amount
required
integer <int64> (Money)

Partial COD: paid online before shipping; the rest on delivery

via_passport
required
boolean

Placed with a Nouq Passport (verified phone)

loyalty_points
required
integer

Points spent on the order

loyalty_amount
required
integer <int64> (Money)

What the points took off (also in discount_total)

referral_amount
required
integer <int64> (Money)

Friend-referral discount (also in discount_total)

offer_total
required
integer <int64> (Money)

A landing page's quantity offer (also in discount_total)

upsell_total
required
integer <int64> (Money)

What cross-sell and post-purchase offers took off (also in discount_total)

landing_page_id
required
string or null <uuid>

The landing page the order came from

phone_whatsapp
required
boolean or null

Whether the shopper said their number is on WhatsApp (null: not asked)

parent_order_id
required
string or null <uuid>

The order this one ships with: an after-order offer accepted on a paid card order becomes its own small order, paid on its own

required
object (Customer)
required
object (Address)
shipping_method
required
string
note
required
string
required
Array of objects (FieldAnswer)

Answers to the store's checkout questions

payment_discount
required
integer <int64> (Money)

What paying this way took off (also in discount_total)

bank_offer
required
string

The bank whose card offer the order took (its amount is in payment_discount)

card_prefix
required
string

First 6 digits the shopper gave for that offer

paid_card_prefix
required
string

First 6 digits of the card the gateway reports paid (empty: not reported yet)

bank_offer_mismatch
required
boolean

The card that paid isn't in the offer

cod_confirmed_at
required
string or null <date-time>
cod_reminders
required
integer

Confirmation reminders sent (COD)

cod_expires_at
required
string or null <date-time>

When an unconfirmed COD order cancels itself

address_confirmed_at
required
string or null <date-time>
delivery_window
required
string
Enum: "" "morning" "afternoon" "evening"
required
Array of objects (OrderItem)
required
Array of objects (Shipment)
created_at
required
string <date-time>
updated_at
required
string <date-time>
Array of objects (OrderEvent)

Merchant view only

next_actions
Array of strings (OrderStatus)
Items Enum: "pending_confirmation" "pending_payment" "confirmed" "processing" "shipped" "delivered" "cancelled"

Merchant view only

Request samples

Content type
application/json
{
  • "confirm": true,
  • "address": {
    • "short_address": "string",
    • "landmark": "string",
    • "lat": 0,
    • "lng": 0,
    • "notes": "string",
    • "delivery_window": ""
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": 0,
  • "token": "string",
  • "status": "pending_confirmation",
  • "payment_method": "cod",
  • "payment_status": "unpaid",
  • "currency": "string",
  • "subtotal": 0,
  • "shipping_total": 0,
  • "cod_fee": 0,
  • "discount_total": 0,
  • "discount_code": "string",
  • "recovered_from_cart": true,
  • "vat_total": 0,
  • "total": 0,
  • "refunded_total": 0,
  • "deposit_amount": 0,
  • "via_passport": true,
  • "loyalty_points": 0,
  • "loyalty_amount": 0,
  • "referral_amount": 0,
  • "offer_total": 0,
  • "upsell_total": 0,
  • "landing_page_id": "414a5bce-f320-4a62-9fa5-1a44e5cc334f",
  • "phone_whatsapp": true,
  • "parent_order_id": "aca22822-0c4a-4277-bcc3-199a8417c244",
  • "customer": {
    • "name": "string",
    • "phone": "string",
    • "email": "string"
    },
  • "address": {
    • "city": "string",
    • "district": "string",
    • "street": "string",
    • "building_number": "string",
    • "additional_number": "string",
    • "postal_code": "string",
    • "short_address": "string",
    • "floor": "string",
    • "apartment": "string",
    • "landmark": "string",
    • "lat": 0,
    • "lng": 0,
    • "notes": "string"
    },
  • "shipping_method": "string",
  • "note": "string",
  • "custom_fields": [
    • {
      }
    ],
  • "payment_discount": 0,
  • "bank_offer": "string",
  • "card_prefix": "string",
  • "paid_card_prefix": "string",
  • "bank_offer_mismatch": true,
  • "cod_confirmed_at": "2019-08-24T14:15:22Z",
  • "cod_reminders": 0,
  • "cod_expires_at": "2019-08-24T14:15:22Z",
  • "address_confirmed_at": "2019-08-24T14:15:22Z",
  • "delivery_window": "",
  • "items": [
    • {
      }
    ],
  • "shipments": [
    • {
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "events": [
    • {
      }
    ],
  • "next_actions": [
    • "pending_confirmation"
    ]
}

startPayment

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
provider
required
string
method
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

status
required
string
Enum: "initiated" "paid" "failed"
amount
required
integer <int64> (Money)

Minor units (halalas)

currency
required
string
order_token
required
string
order_number
required
integer
redirect_url
string
reference
string

Still pending: a code the shopper pays offline (a Fawry reference at a kiosk)

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "provider": "string",
  • "method": "cod",
  • "status": "initiated",
  • "amount": 0,
  • "currency": "string",
  • "order_token": "string",
  • "order_number": 0,
  • "redirect_url": "string",
  • "reference": "string"
}

getPayment

path Parameters
id
required
string <uuid>
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
provider
required
string
method
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

status
required
string
Enum: "initiated" "paid" "failed"
amount
required
integer <int64> (Money)

Minor units (halalas)

currency
required
string
order_token
required
string
order_number
required
integer
redirect_url
string
reference
string

Still pending: a code the shopper pays offline (a Fawry reference at a kiosk)

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "provider": "string",
  • "method": "cod",
  • "status": "initiated",
  • "amount": 0,
  • "currency": "string",
  • "order_token": "string",
  • "order_number": 0,
  • "redirect_url": "string",
  • "reference": "string"
}

confirmPayment

The shopper is back from the merchant's gateway. Reads the payment's real status from the gateway and settles it.

path Parameters
id
required
string <uuid>
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
provider
required
string
method
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

status
required
string
Enum: "initiated" "paid" "failed"
amount
required
integer <int64> (Money)

Minor units (halalas)

currency
required
string
order_token
required
string
order_number
required
integer
redirect_url
string
reference
string

Still pending: a code the shopper pays offline (a Fawry reference at a kiosk)

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "provider": "string",
  • "method": "cod",
  • "status": "initiated",
  • "amount": 0,
  • "currency": "string",
  • "order_token": "string",
  • "order_number": 0,
  • "redirect_url": "string",
  • "reference": "string"
}

storefrontPixels

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
Array of objects (PublicPixel)

Meta

ga4_measurement_id
required
string
gads_id
required
string
gads_label
required
string
gads_enhanced
required
boolean

Google Ads enhanced conversions: give gtag the shopper's email and phone on purchase.

consent_banner
required
boolean

Ask shoppers before loading ad pixels.

ga4_server_purchase
required
boolean

Purchases reach GA4 from the server; the page must not send its own.

Response samples

Content type
application/json
{
  • "pixels": [
    • {
      }
    ],
  • "ga4_measurement_id": "string",
  • "gads_id": "string",
  • "gads_label": "string",
  • "gads_enhanced": true,
  • "consent_banner": true,
  • "ga4_server_purchase": true
}

pixelsFired

Counts an event the browser sent to pixels, for the merchant's pixel health.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
event
required
string
Enum: "page_view" "view_item" "add_to_cart" "begin_checkout" "purchase"
event_id
string
pixels
Array of strings

The pixels it reached, as "platform:id".

foreign
Array of strings

Platforms whose code something else had already loaded on the page.

Responses

Request samples

Content type
application/json
{
  • "event": "page_view",
  • "event_id": "string",
  • "pixels": [
    • "string"
    ],
  • "foreign": [
    • "string"
    ]
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

trackEvent

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
visitor_id
required
string <uuid>
session_id
required
string <uuid>
type
required
string
Enum: "page_view" "view_item" "add_to_cart" "begin_checkout"
event_id
string

Shared with the browser pixels so platforms count the event once.

url
string
referrer
string
product_id
string or null <uuid>
variant_id
string or null <uuid>
landing_id
string or null <uuid>

The landing page the event happened on.

quantity
integer
cart_token
string
consent
string
Enum: "granted" "denied" ""
object (TrackClient)

Responses

Request samples

Content type
application/json
{
  • "visitor_id": "1b5d452e-2897-4f21-ac74-1b59f820ba97",
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "type": "page_view",
  • "event_id": "string",
  • "url": "string",
  • "referrer": "string",
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "quantity": 0,
  • "cart_token": "string",
  • "consent": "granted",
  • "client": {
    • "ip": "string",
    • "user_agent": "string",
    • "fbp": "string",
    • "fbc": "string",
    • "ttp": "string",
    • "scid": "string",
    • "ga": "string",
    • "epik": "string"
    }
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

catalogFeed

Product feed for Meta, TikTok, Snapchat and Google Merchant Center (Google product format; CSV for Meta).

path Parameters
token
required
string
file
required
string
Enum: "products.xml" "products.csv"
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema:
string

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

storefrontPaymentMethods

query Parameters
total
integer

Order total in halalas

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
Array of objects (PaymentOption)
required
Array of objects (BankAccount)
bank_transfer_hours
required
integer

Response samples

Content type
application/json
{
  • "options": [
    • {
      }
    ],
  • "bank_accounts": [
    • {
      }
    ],
  • "bank_transfer_hours": 0
}

orderTransfer

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
amount
required
integer <int64> (Money)

Minor units (halalas)

currency
required
string
required
Array of objects (BankAccount)
deadline
required
string <date-time>
state
required
string
Enum: "awaiting" "review" "paid" "cancelled"
required
Array of objects (TransferReceipt)

Response samples

Content type
application/json
{
  • "amount": 0,
  • "currency": "string",
  • "accounts": [
    • {
      }
    ],
  • "deadline": "2019-08-24T14:15:22Z",
  • "state": "awaiting",
  • "receipts": [
    • {
      }
    ]
}

uploadTransferReceipt

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: multipart/form-data
required
receipt
required
string <binary>
note
string

Responses

Response Schema: application/json
id
required
string <uuid>
order_id
required
string <uuid>
content_type
required
string
note
required
string
status
required
string
Enum: "pending" "accepted" "rejected"
reject_reason
required
string
created_at
required
string <date-time>
decided_at
required
string or null <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "content_type": "string",
  • "note": "string",
  • "status": "pending",
  • "reject_reason": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "decided_at": "2019-08-24T14:15:22Z"
}

storefrontSalesProof

Sales notices from the store's real recent orders (empty when off or fewer than two).

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
pages
required
Array of strings
required
Array of objects (RecentPurchase)

Response samples

Content type
application/json
{
  • "pages": [
    • "string"
    ],
  • "items": [
    • {
      }
    ]
}

storefrontCheckoutFields

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
key
required
string

Kept across edits; empty for a new question

label_ar
required
string <= 60 characters
label_en
string <= 60 characters
type
required
string
Enum: "text" "textarea" "select"
options
Array of strings

select only: 2–20 choices

required
required
boolean

Response samples

Content type
application/json
[
  • {
    • "key": "string",
    • "label_ar": "string",
    • "label_en": "string",
    • "type": "text",
    • "options": [
      ],
    • "required": true
    }
]

checkoutShippingRates

query Parameters
cart_token
string
city
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
name_ar
required
string
name_en
required
string
eta_ar
required
string
eta_en
required
string
carrier
required
string
price
required
integer <int64> (Money)

Minor units (halalas)

eta_min
required
integer

Business days from the carrier (0 = use eta_ar/eta_en)

eta_max
required
integer
available
required
boolean
reason
string

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name_ar": "string",
    • "name_en": "string",
    • "eta_ar": "string",
    • "eta_en": "string",
    • "carrier": "string",
    • "price": 0,
    • "eta_min": 0,
    • "eta_max": 0,
    • "available": true,
    • "reason": "string"
    }
]

orderTracking

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
Array
id
required
string <uuid>
order_id
required
string <uuid>
carrier
required
string
carrier_name
required
string
sandbox
required
boolean
tracking_number
required
string
track_url
required
string
status
required
string (ParcelStatus)
Enum: "label_created" "picked_up" "in_transit" "out_for_delivery" "delivered" "failed_attempt" "returned" "cancelled"
weight_grams
required
integer
cost
required
integer <int64> (Money)

Minor units (halalas)

cod_amount
required
integer <int64> (Money)

Minor units (halalas)

mode
required
string (CarrierMode)
Enum: "own" "nouq"

own: the merchant's carrier contract; nouq: Nouq Shipping (Nouq's contract, paid from the shipping balance, ADR 0020)

currency
required
string
retail
required
integer <int64> (Money)

Walk-in rate the Nouq price compares with (nouq mode)

cod_fee
required
integer <int64> (Money)

Charged for collecting the cash (nouq mode)

object (ParcelLabel)
pickup_ref
required
string
pickup_at
required
string or null <date-time>
required
Array of objects (ParcelEvent)
delivered_at
required
string or null <date-time>
created_at
required
string <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    • "carrier": "string",
    • "carrier_name": "string",
    • "sandbox": true,
    • "tracking_number": "string",
    • "track_url": "string",
    • "status": "label_created",
    • "weight_grams": 0,
    • "cost": 0,
    • "cod_amount": 0,
    • "mode": "own",
    • "currency": "string",
    • "retail": 0,
    • "cod_fee": 0,
    • "label": {
      },
    • "pickup_ref": "string",
    • "pickup_at": "2019-08-24T14:15:22Z",
    • "events": [
      ],
    • "delivered_at": "2019-08-24T14:15:22Z",
    • "created_at": "2019-08-24T14:15:22Z"
    }
]

codCheck

Whether cash on delivery needs a deposit or isn't available for this buyer and total (the decision is made again at checkout).

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
phone
required
string
total
required
integer <int64> (Money)

Minor units (halalas)

shipping_total
integer <int64> (Money)

Minor units (halalas)

object (Address)
cart_token
string

The cart, so products that always need a deposit and a phone already proven with a code count

Responses

Response Schema: application/json
action
required
string
Enum: "auto_confirm" "whatsapp" "otp" "deposit" "block"
deposit
required
integer <int64> (Money)

Minor units (halalas)

trusted
required
boolean

Request samples

Content type
application/json
{
  • "phone": "string",
  • "total": 0,
  • "shipping_total": 0,
  • "address": {
    • "city": "string",
    • "district": "string",
    • "street": "string",
    • "building_number": "string",
    • "additional_number": "string",
    • "postal_code": "string",
    • "short_address": "string",
    • "floor": "string",
    • "apartment": "string",
    • "landmark": "string",
    • "lat": 0,
    • "lng": 0,
    • "notes": "string"
    },
  • "cart_token": "string"
}

Response samples

Content type
application/json
{
  • "action": "auto_confirm",
  • "deposit": 0,
  • "trusted": true
}

requestCheckoutPhoneCode

Sends the code checkout asked for (422 with fields.phone_code) by SMS. 409 phone_code_not_needed when the store's policy never asks for one.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
cart_token
required
string
phone
required
string

Responses

Response Schema: application/json
phone
required
string
expires_in
required
integer
dev_code
string

Local development only

Request samples

Content type
application/json
{
  • "cart_token": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "phone": "string",
  • "expires_in": 0,
  • "dev_code": "string"
}

verifyCheckoutPhoneCode

Checks the code and marks the phone proven on the cart; checkout then confirms the order.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
cart_token
required
string
phone
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "cart_token": "string",
  • "phone": "string",
  • "code": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

storefrontTrustBadge

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
earned
required
boolean
met
required
Array of strings

Response samples

Content type
application/json
{
  • "earned": true,
  • "met": [
    • "string"
    ]
}

resolveRedirect

Where a path with no page should permanently redirect, from the store's redirects or from the URL shapes of Shopify, Zid and Salla.

query Parameters
path
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
to
required
string

Response samples

Content type
application/json
{
  • "to": "string"
}

sitemapProducts

Active products for one sitemap file (5,000 per page, oldest first).

query Parameters
page
integer >= 1
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
total
required
integer
per_page
required
integer
required
Array of objects

Response samples

Content type
application/json
{
  • "total": 0,
  • "per_page": 0,
  • "items": [
    • {
      }
    ]
}

storefrontReturnPolicy

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
enabled
required
boolean
window_days
required
integer [ 1 .. 90 ]
exchanges
required
boolean
policy
required
string

Response samples

Content type
application/json
{
  • "enabled": true,
  • "window_days": 1,
  • "exchanges": true,
  • "policy": "string"
}

storefrontSEOVerification

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
google_verification
required
string

The content of Google's site-verification meta tag (the whole tag is accepted on save)

bing_verification
required
string

Response samples

Content type
application/json
{
  • "google_verification": "string",
  • "bing_verification": "string"
}

passportExchange

The store's server swaps the one-time code from my.nouq.net for a link token.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
code
required
string

Responses

Response Schema: application/json
link_token
required
string
required
object (PassportStoreProfile)

What a connected store sees (only the granted scopes; cards without tokens)

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "link_token": "string",
  • "profile": {
    • "passport_id": "65168a94-b41d-4d9a-a11b-d91c55150994",
    • "name": "string",
    • "phone": "string",
    • "email": "string",
    • "addresses": [
      ],
    • "sizes": {
      },
    • "cards": [
      ],
    • "scopes": [
      ]
    }
}

accountRegister

Opens a shopper account on this store and signs it in; a code to confirm the email goes out too.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
email
required
string
password
required
string
name
string
phone
string

Responses

Response Schema: application/json
token
required
string

Kept by the store's server in an httpOnly cookie on its own domain

expires_at
required
string <date-time>
required
object (ShopperAccount)

A shopper's account on one store (ADR 0023).

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "name": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "account": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "email": "string",
    • "name": "string",
    • "phone": "string",
    • "email_verified": true,
    • "created_at": "2019-08-24T14:15:22Z"
    }
}

accountLogin

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
email
required
string
password
required
string

Responses

Response Schema: application/json
token
required
string

Kept by the store's server in an httpOnly cookie on its own domain

expires_at
required
string <date-time>
required
object (ShopperAccount)

A shopper's account on one store (ADR 0023).

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "account": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "email": "string",
    • "name": "string",
    • "phone": "string",
    • "email_verified": true,
    • "created_at": "2019-08-24T14:15:22Z"
    }
}

accountLogout

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

accountMe

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string

Responses

Response Schema: application/json
id
required
string <uuid>
email
required
string
name
required
string
phone
required
string
email_verified
required
boolean
created_at
required
string <date-time>

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "name": "string",
  • "phone": "string",
  • "email_verified": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

accountUpdate

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string
Request Body schema: application/json
required
name
string
phone
string

Responses

Response Schema: application/json
id
required
string <uuid>
email
required
string
name
required
string
phone
required
string
email_verified
required
boolean
created_at
required
string <date-time>

Request samples

Content type
application/json
{
  • "name": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "name": "string",
  • "phone": "string",
  • "email_verified": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

accountChangePassword

Needs the current password; signs every other device out.

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string
Request Body schema: application/json
required
current_password
required
string
new_password
required
string

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

accountRequestVerification

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string

Responses

Response Schema: application/json
email
required
string
expires_in
required
integer
dev_code
string

Local development only

Response samples

Content type
application/json
{
  • "email": "string",
  • "expires_in": 0,
  • "dev_code": "string"
}

accountVerify

Confirms the email; earlier guest orders with it then show in the account.

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string
Request Body schema: application/json
required
code
required
string

Responses

Response Schema: application/json
id
required
string <uuid>
email
required
string
name
required
string
phone
required
string
email_verified
required
boolean
created_at
required
string <date-time>

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "name": "string",
  • "phone": "string",
  • "email_verified": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

accountRequestReset

Emails a reset code. Answers the same whether or not the email has an account.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
email
required
string

Responses

Response Schema: application/json
email
required
string
expires_in
required
integer
dev_code
string

Local development only

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "email": "string",
  • "expires_in": 0,
  • "dev_code": "string"
}

accountReset

Sets a new password with the emailed code, signs out every device and signs in here.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
email
required
string
code
required
string
password
required
string

Responses

Response Schema: application/json
token
required
string

Kept by the store's server in an httpOnly cookie on its own domain

expires_at
required
string <date-time>
required
object (ShopperAccount)

A shopper's account on one store (ADR 0023).

Request samples

Content type
application/json
{
  • "email": "string",
  • "code": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "account": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "email": "string",
    • "name": "string",
    • "phone": "string",
    • "email_verified": true,
    • "created_at": "2019-08-24T14:15:22Z"
    }
}

accountOrders

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string

Responses

Response Schema: application/json
required
Array of objects (ShopperOrder)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

accountDelete

Closes the account for good (the password confirms it). Orders stay with the store.

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Account-Token
required
string
Request Body schema: application/json
required
password
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

passportForStore

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Passport-Token
required
string

Responses

Response Schema: application/json
passport_id
required
string <uuid>
name
required
string
phone
required
string
email
required
string
required
Array of objects (PassportAddress)
required
object
required
Array of objects (PassportCard)
scopes
required
Array of strings

Response samples

Content type
application/json
{
  • "passport_id": "65168a94-b41d-4d9a-a11b-d91c55150994",
  • "name": "string",
  • "phone": "string",
  • "email": "string",
  • "addresses": [
    • {
      }
    ],
  • "sizes": {
    • "property1": "string",
    • "property2": "string"
    },
  • "cards": [
    • {
      }
    ],
  • "scopes": [
    • "string"
    ]
}

passportPayment

One tap with a card saved on the shopper's Passport (needs the cards scope).

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Passport-Token
required
string
Request Body schema: application/json
required
card_id
required
string <uuid>

Responses

Response Schema: application/json
id
required
string <uuid>
provider
required
string
method
string (PaymentMethod)
Enum: "cod" "card" "stc_pay" "tabby" "tamara" "bank_transfer" "net_terms" "exchange"

exchange = zero-cost replacement order from a return; net_terms = a business account's credit terms (pay later)

status
required
string
Enum: "initiated" "paid" "failed"
amount
required
integer <int64> (Money)

Minor units (halalas)

currency
required
string
order_token
required
string
order_number
required
integer
redirect_url
string
reference
string

Still pending: a code the shopper pays offline (a Fawry reference at a kiosk)

Request samples

Content type
application/json
{
  • "card_id": "66f6e46c-f6a1-4af8-a1bd-49666bc01304"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "provider": "string",
  • "method": "cod",
  • "status": "initiated",
  • "amount": 0,
  • "currency": "string",
  • "order_token": "string",
  • "order_number": 0,
  • "redirect_url": "string",
  • "reference": "string"
}

requestLoyaltyCode

Sends a WhatsApp code that proves the phone before its points are spent.

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
phone
required
string

Responses

Response Schema: application/json
phone
required
string
expires_in
required
integer
dev_code
string

Only in local development

demo
boolean

The public demo account (0500000000); dev_code is shown on screen

Request samples

Content type
application/json
{
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "phone": "string",
  • "expires_in": 0,
  • "dev_code": "string",
  • "demo": true
}

useLoyalty

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Passport-Token
string

Skips the code when its phone matches

X-Account-Token
string

The signed-in store account: skips the code when its email is verified and one of its orders was delivered to the phone

Request Body schema: application/json
required
phone
required
string
code
string

WhatsApp code; not needed when the phone is already proven on the cart or by Passport

points
integer

0 spends as many as the cart allows

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "phone": "string",
  • "code": "string",
  • "points": 0
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

removeLoyalty

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Passport-Token
string

Skips the code when its phone matches

X-Account-Token
string

The signed-in store account: skips the code when its email is verified and one of its orders was delivered to the phone

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

useReferral

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
code
required
string

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

removeReferral

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

orderRewards

Points earned and the shopper's referral link, on their order page.

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
required
object or null
required
object or null

Response samples

Content type
application/json
{
  • "loyalty": {
    • "earned": 0,
    • "pending": 0,
    • "spent": 0,
    • "account": {
      },
    • "point_value": 0
    },
  • "referral": {
    • "code": "string",
    • "path": "string",
    • "friend_amount": 0,
    • "min_subtotal": 0,
    • "referrer_amount": 0,
    • "referrer_reward": "coupon",
    • "invited": 0,
    • "rewarded": 0
    }
}

rewardPrograms

The store's points and referral programmes, as shoppers see them.

header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
phone_codes
required
boolean

Codes can be sent to phones (PHONE_CODES): offer spending points by phone code, and Nouq Passport

required
object
required
object

Response samples

Content type
application/json
{
  • "phone_codes": true,
  • "loyalty": {
    • "enabled": true,
    • "earn_rate": 0,
    • "point_value": 0,
    • "min_redeem": 0,
    • "max_redeem_pct": 0
    },
  • "referral": {
    • "enabled": true,
    • "friend_amount": 0,
    • "min_subtotal": 0,
    • "referrer_amount": 0
    }
}

businessMe

The store's wholesale programme and the signed-in business buyer, if any.

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Responses

Response Schema: application/json
enabled
required
boolean
pitch
required
string
min_order
required
integer <int64> (Money)

Minor units (halalas)

quotes_enabled
required
boolean
phone
required
string

The verified phone ("" when signed out)

required
BusinessAccount (object) or null
credit_available
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (BusinessPrefill)

Nouq stores the phone runs

required
Array of objects (WholesaleOrderLine)
required
Array of objects (QuoteSummary)

Response samples

Content type
application/json
{
  • "enabled": true,
  • "pitch": "string",
  • "min_order": 0,
  • "quotes_enabled": true,
  • "phone": "string",
  • "account": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "phone": "string",
    • "company_name": "string",
    • "vat_number": "string",
    • "cr_number": "string",
    • "contact_name": "string",
    • "email": "string",
    • "address": {
      },
    • "buyer_store_id": "4e653165-cf5a-407f-8778-8bed7a4c68cc",
    • "buyer_store": "string",
    • "status": "pending",
    • "terms_days": 0,
    • "credit_limit": 0,
    • "note": "string",
    • "created_at": "2019-08-24T14:15:22Z",
    • "decided_at": "2019-08-24T14:15:22Z",
    • "orders": 0,
    • "sales": 0,
    • "open_balance": 0,
    • "overdue": 0
    },
  • "credit_available": 0,
  • "prefill": [
    • {
      }
    ],
  • "orders": [
    • {
      }
    ],
  • "quotes": [
    • {
      }
    ]
}

requestBusinessCode

header Parameters
X-Nouq-Host
string
Example: test.localhost
Request Body schema: application/json
required
phone
required
string

Responses

Response Schema: application/json
phone
required
string
expires_in
required
integer
dev_code
string

Only in local development

demo
boolean

The public demo account (0500000000); dev_code is shown on screen

Request samples

Content type
application/json
{
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "phone": "string",
  • "expires_in": 0,
  • "dev_code": "string",
  • "demo": true
}

businessSignIn

Check the WhatsApp code; the token goes in X-Business-Token afterwards.

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Request Body schema: application/json
required
phone
required
string
code
required
string

Responses

Response Schema: application/json
token
required
string
required
object (BusinessMe)

Request samples

Content type
application/json
{
  • "phone": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "me": {
    • "enabled": true,
    • "pitch": "string",
    • "min_order": 0,
    • "quotes_enabled": true,
    • "phone": "string",
    • "account": {
      },
    • "credit_available": 0,
    • "prefill": [
      ],
    • "orders": [
      ],
    • "quotes": [
      ]
    }
}

businessSignOut

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}

applyBusinessAccount

header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Request Body schema: application/json
required
phone
string

Adding an account only

company_name
required
string
vat_number
string
cr_number
string
contact_name
string
email
string
object (BusinessAddress)
status
string (BusinessAccountStatus)
Enum: "pending" "approved" "rejected" "suspended"
terms_days
integer
credit_limit
integer <int64> (Money)

Minor units (halalas)

note
string
buyer_store_id
string or null <uuid>

Applying: as this Nouq store (one the verified phone runs)

Responses

Response Schema: application/json
enabled
required
boolean
pitch
required
string
min_order
required
integer <int64> (Money)

Minor units (halalas)

quotes_enabled
required
boolean
phone
required
string

The verified phone ("" when signed out)

required
BusinessAccount (object) or null
credit_available
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (BusinessPrefill)

Nouq stores the phone runs

required
Array of objects (WholesaleOrderLine)
required
Array of objects (QuoteSummary)

Request samples

Content type
application/json
{
  • "phone": "string",
  • "company_name": "string",
  • "vat_number": "string",
  • "cr_number": "string",
  • "contact_name": "string",
  • "email": "string",
  • "address": {
    • "street": "string",
    • "building_number": "string",
    • "district": "string",
    • "city": "string",
    • "postal_code": "string"
    },
  • "status": "pending",
  • "terms_days": 0,
  • "credit_limit": 0,
  • "note": "string",
  • "buyer_store_id": "4e653165-cf5a-407f-8778-8bed7a4c68cc"
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "pitch": "string",
  • "min_order": 0,
  • "quotes_enabled": true,
  • "phone": "string",
  • "account": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "phone": "string",
    • "company_name": "string",
    • "vat_number": "string",
    • "cr_number": "string",
    • "contact_name": "string",
    • "email": "string",
    • "address": {
      },
    • "buyer_store_id": "4e653165-cf5a-407f-8778-8bed7a4c68cc",
    • "buyer_store": "string",
    • "status": "pending",
    • "terms_days": 0,
    • "credit_limit": 0,
    • "note": "string",
    • "created_at": "2019-08-24T14:15:22Z",
    • "decided_at": "2019-08-24T14:15:22Z",
    • "orders": 0,
    • "sales": 0,
    • "open_balance": 0,
    • "overdue": 0
    },
  • "credit_available": 0,
  • "prefill": [
    • {
      }
    ],
  • "orders": [
    • {
      }
    ],
  • "quotes": [
    • {
      }
    ]
}

businessProductTiers

The product's wholesale tiers, for an approved business buyer.

path Parameters
slug
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Responses

Response Schema: application/json
Array
variant_id
required
string <uuid>
required
Array of objects (PriceTier)

Response samples

Content type
application/json
[
  • {
    • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
    • "tiers": [
      ]
    }
]

linkBusinessCart

Price the cart for the signed-in buyer's approved account.

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

unlinkBusinessCart

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Responses

Response Schema: application/json
token
required
string
required
Array of objects (CartItem)
item_count
required
integer
subtotal
required
integer <int64> (Money)

Minor units (halalas)

required
Array of objects (AppliedDiscount)

Every discount the cart gets, in the order they come off (product, order, shipping): its coupon and the automatic discounts that stack with it, or the best automatic ones

required
AppliedDiscount (object) or null

The main one of discounts (the coupon, else the largest); show discounts instead

discount_code
required
string
discount_stale
required
boolean
required
DiscountNudge (object) or null

The automatic discount the shopper is closest to

required
object (CartRewards)
required
CartOffer (object) or null

A landing page's quantity offer, when the cart came from one

landing_id
required
string or null <uuid>
required
Array of objects (CartUpsell)

Cross-sell offers the cart gets (one discounted piece each); never on landing-page carts

required
Array of objects (UpsellSuggestion)

Cross-sell offers for products not yet in the cart (at most 3)

required
CartBusiness (object) or null

The business account the cart is priced for (wholesale; no coupons, offers or rewards)

total
required
integer <int64> (Money)

Subtotal after offer, upsells, discount and rewards, before shipping

checkoutable
required
boolean
free_shipping
required
boolean

Ships free without a coupon: every product in it ships free, or a quantity tier that does was reached

min_order
required
integer <int64> (Money)

The store's minimum order (0: none)

below_minimum
required
boolean

The products after offers and discounts don't reach min_order, so the cart can't be checked out

min_order_gap
required
integer <int64> (Money)

What's still missing to reach min_order

Response samples

Content type
application/json
{
  • "token": "string",
  • "items": [
    • {
      }
    ],
  • "item_count": 0,
  • "subtotal": 0,
  • "discounts": [
    • {
      }
    ],
  • "discount": {
    • "code": "string",
    • "title": "string",
    • "type": "percent",
    • "amount": 0,
    • "free_shipping": true
    },
  • "discount_code": "string",
  • "discount_stale": true,
  • "next_discount": {
    • "title": "string",
    • "type": "percent",
    • "missing_quantity": 0,
    • "missing_amount": 0
    },
  • "rewards": {
    • "loyalty": {
      },
    • "referral": {
      }
    },
  • "offer": {
    • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
    • "label": "string",
    • "quantity": 0,
    • "amount": 0,
    • "free_shipping": true
    },
  • "landing_id": "c4bddb18-aee3-4e26-879f-e43a4236727c",
  • "upsells": [
    • {
      }
    ],
  • "suggestions": [
    • {
      }
    ],
  • "business": {
    • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    • "company_name": "string",
    • "terms_days": 0,
    • "credit_available": 0,
    • "min_order": 0,
    • "below_minimum": true,
    • "quotes_enabled": true,
    • "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",
    • "quote_number": 0,
    • "savings": 0
    },
  • "total": 0,
  • "checkoutable": true,
  • "free_shipping": true,
  • "min_order": 0,
  • "below_minimum": true,
  • "min_order_gap": 0
}

requestQuote

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Request Body schema: application/json
optional
note
string

Responses

Response Schema: application/json
id
required
string <uuid>
number
required
integer
account_id
required
string <uuid>
company_name
required
string
status
required
string (QuoteStatus)
Enum: "requested" "sent" "accepted" "declined" "ordered" "expired"
total
required
integer <int64> (Money)

Minor units (halalas)

pieces
required
integer
valid_until
required
string or null <date-time>
sent_at
required
string or null <date-time>
order_id
required
string or null <uuid>
created_at
required
string <date-time>
token
required
string

The buyer's link token (merchant views only)

buyer_note
required
string
merchant_note
required
string
required
Array of objects (QuoteLine)
list_total
required
integer <int64> (Money)

Minor units (halalas)

link
required
string

The buyer's page for the quote

store_name
required
string
currency
required
string

Request samples

Content type
application/json
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": 0,
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "company_name": "string",
  • "status": "requested",
  • "total": 0,
  • "pieces": 0,
  • "valid_until": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "created_at": "2019-08-24T14:15:22Z",
  • "token": "string",
  • "buyer_note": "string",
  • "merchant_note": "string",
  • "lines": [
    • {
      }
    ],
  • "list_total": 0,
  • "link": "string",
  • "store_name": "string",
  • "currency": "string"
}

quoteByToken

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost

Responses

Response Schema: application/json
id
required
string <uuid>
number
required
integer
account_id
required
string <uuid>
company_name
required
string
status
required
string (QuoteStatus)
Enum: "requested" "sent" "accepted" "declined" "ordered" "expired"
total
required
integer <int64> (Money)

Minor units (halalas)

pieces
required
integer
valid_until
required
string or null <date-time>
sent_at
required
string or null <date-time>
order_id
required
string or null <uuid>
created_at
required
string <date-time>
token
required
string

The buyer's link token (merchant views only)

buyer_note
required
string
merchant_note
required
string
required
Array of objects (QuoteLine)
list_total
required
integer <int64> (Money)

Minor units (halalas)

link
required
string

The buyer's page for the quote

store_name
required
string
currency
required
string

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "number": 0,
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "company_name": "string",
  • "status": "requested",
  • "total": 0,
  • "pieces": 0,
  • "valid_until": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "created_at": "2019-08-24T14:15:22Z",
  • "token": "string",
  • "buyer_note": "string",
  • "merchant_note": "string",
  • "lines": [
    • {
      }
    ],
  • "list_total": 0,
  • "link": "string",
  • "store_name": "string",
  • "currency": "string"
}

acceptQuote

Fill the cart (or a new one) with the quote's lines at its prices.

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Request Body schema: application/json
optional
cart_token
string

Responses

Response Schema: application/json
cart_token
required
string

Request samples

Content type
application/json
{
  • "cart_token": "string"
}

Response samples

Content type
application/json
{
  • "cart_token": "string"
}

declineQuoteAsBuyer

path Parameters
token
required
string
header Parameters
X-Nouq-Host
string
Example: test.localhost
X-Business-Token
string

A business buyer's storefront session (wholesale)

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "fields": {
    • "property1": "string",
    • "property2": "string"
    }
}