Zid | زد

View saved version →

---
name: abandoned-carts
description: Recover a Zid store's abandoned carts. Use to see how many carts are abandoned and where checkout stops, set up or tune Zid's automatic cart reminders with a discount or free-shipping offer, prepare the reminder coupon and WhatsApp text, list high-value carts for the merchant to follow up, or measure recovered sales.
---

# Abandoned carts

Finds where shoppers drop out, sets up the store's own reminders, and measures
what comes back.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- Reminders go through Zid's own reminder settings or the merchant's tools; this
  skill configures and measures them.
- Show each setting change and coupon before making it and apply it after the
  merchant agrees. When a manage tool answers `confirmation_required`, compare
  its plan with what the merchant approved: if they match, repeat the call with
  its `plan_id`; if not, show the plan and ask again.
- A discount code in an SMS is promotional: Zid sends it only from a promotional
  sender name (ending in `AD`). WhatsApp reminder texts go to Meta for approval
  before they send; email and SMS start when saved.

## 1. Read the carts

- `zid_orders.list_abandoned_carts` with `dateFrom`, `dateTo`, `pageSize` 100,
  every page; filter with `phase`, `cartTotal`, `productsCount`. One cart with
  its products and customer: `zid_orders.get_abandoned_cart`.
- Rates and recovered sales: `zid_reports.abandoned_carts_rate` and
  `zid_reports.abandoned_cart_sales` (when reports are available for the store).

## 2. Find where checkout stops

Count carts and value by `phase`: `new`, `login`, `shipping_address`,
`shipping_method`, `payment_method`, `verification`, and `completed` (recovered,
reported separately). The phase with the most
value points to the setting to look at: shipping prices and methods for
`shipping_method`, payment options for `payment_method`, and the sign-in step
for `login`. Report the counts; the merchant decides what to change.

Done when every cart in the period sits in one phase and the phase totals add up
to the period total.

## 3. Automatic reminders

1. `zid_campaigns.get_auto_reminder` and
   `zid_campaigns.list_abandoned_cart_reminders` show what runs today.
2. An offer needs a coupon that applies by code. Check that the code is free with
   `zid_promotions.list_coupons` (`searchTerm`), then
   `zid_promotions_manage.create_coupon` with `name`, `code`, `discountType`
   (`p` percent or `f` fixed), `discount`, `dateStart`, `dateEnd`,
   `usesCustomer` 1 and `applyingMethod` `CODE`. A "code already used" error
   means another coupon has it: pick a new code.
3. `zid_campaigns_manage.update_auto_reminder`: `offerType` (`discount`,
   `free_shipping` or `no_offer`), `offerCouponId`, `cartTotal` (the minimum),
   `sendAfter` (hours) and `phases`.
4. `zid_campaigns_manage.set_auto_reminder_status` with `enabled` true.
5. The text the merchant starts from when contacting a cart's customer on
   WhatsApp: `zid_campaigns.get_cart_whatsapp_message` and
   `zid_campaigns_manage.set_cart_whatsapp_message` (up to 1,000 characters).

## 4. High-value carts

List carts above the merchant's threshold with cart id, customer name, products,
value and age, newest first; add contact details only when the merchant asks. The merchant contacts them from the dashboard
(Orders → Abandoned carts, single or bulk alert) or their WhatsApp tool.

## 5. Measure

After 7 and 30 days, compare abandoned value, recovered orders and the coupon's
use (`zid_promotions.list_coupons` or `zid_reports.coupon_performance`) with the
period before the change.

## Output

Carts and value by phase, the reminder setup before and after, the coupon, the
high-value list, and the recovery figures when measuring.

View saved version →

---
name: accounting-export
description: Move a Zid store's sales, returns, payment fees and payouts into an accounting system or ERP such as Qoyod, Daftra, Wafeq, Zoho Books, Odoo, Xero or QuickBooks. Use to prepare a sales-invoice or journal import file, reconcile ZidPay payouts and fees with bank deposits, check that every order reached the books, or close a month.
---

# Accounting export

Turns a period of Zid sales into what the accounting system expects, and checks
that the books and Zid agree.

## Ground rules

- The merchant's explicit instructions, and their accountant's, take precedence over this skill.
- This skill reads Zid and produces files and reconciliations; the merchant
  imports them. Accounting-system credentials (API keys, passwords) stay in that
  system or the merchant's automation tool.
- Use the accountant's chart of accounts, tax codes and posting choices. When one
  is missing, ask rather than invent an account.

## 1. Scope

- **Period** and **what goes**: one sales invoice per order, one summary journal
  per day, payouts and fees, or all three.
- **Target system** and whether a connector already posts Zid orders there:
  `zid_account.list_installed_apps`, then [references/systems.md](references/systems.md).
  An installed app is a candidate, not proof: compare a recent sample of Zid order
  numbers with the accounting system. When the sample shows the connector posting,
  reconcile (step 5) instead of exporting the same sales again.
- **E-invoicing**: `zid_settings.list_einvoicing_units`. When a unit is
  `active`, Zid already issues the ZATCA e-invoices for those sales. The sale goes
  into the accounting system as a record that does not issue or report another
  e-invoice (a draft invoice or a journal, per the system's notes in the
  reference). Confirm that choice with the merchant before building the file.
- **Prices and VAT**: `zid_settings.get_tax_settings` shows whether prices
  include VAT.

Done when the period, the documents, the target, the e-invoicing answer and the VAT basis are settled.

## 2. Read Zid

| Need | Read |
| --- | --- |
| Orders in the period | `zid_orders.list_orders` with `dateFrom`, `dateTo`, `paymentStatus` and `perPage` 100, every page; lines, discounts, shipping and VAT per order from `zid_orders.get_order` |
| Large periods | `zid_orders_manage.export_orders` with `exportType` `detailed` (one row per product), `dateFrom` and `dateTo`; Zid emails the file, and it needs the merchant's approval |
| Returns | `zid_orders.get_credit_notes` for each returned or partly returned order |
| Period totals to check against | `zid_reports.sales_report` (revenue, discounts, shipping, tax, cost of goods, returns; `components` such as `payment_methods` or `channel`). When reports are unavailable for the store, total the orders instead |
| ZidPay payouts | `zid_payments.list_zidpay_deposits`, then `zid_payments.get_zidpay_deposit` with the numeric `depositId` for the transactions in each payout |
| ZidPay fees not yet paid out | `zid_payments.get_account_statement` with `settlementStatus` `not_yet_paid_out` or `payout_pending` (fees, VAT on fees, net, running balance) |
| Refunds | `zid_payments.list_refunds` |
| Zid Ship costs and cash on delivery | `zid_shipping.list_shipping_charges` (labels, COD fees, returns), `zid_shipping.list_cod_collected`; other carriers from their invoice or settlement report |

## 3. Build the file

Map to the target's template from [references/systems.md](references/systems.md).
When the merchant has the template, match its exact headers.

- **Keys**: the Zid order number as the invoice number or reference, and the SKU
  as the item code. Duplicate handling differs by system: before a rerun, check
  the existing references (or use the target's External ID where it has one).
- **Lines**: one per product, plus shipping and cash-on-delivery fees as lines;
  discounts per line or as a discount line, the way the target takes them.
- **Money**: plain decimals in the store currency, no symbols; VAT inclusive or
  exclusive as settled in step 1, with the target's tax code name.
- **Returns**: a credit note (or reversing journal) referencing the original invoice.
- **Customers**: the customer number or name the target matches on; business
  customers carry their VAT number.
- **Size**: split files at the target's row limit; keep each invoice's lines in one file.

## 4. Payouts and fees

For each ZidPay payout: payout amount = payments in it − refunds − fees − VAT on
fees. Post the fees and their VAT to the accounts the accountant names, and
match the payout to the bank deposit by its reference. Do the same for courier
cash-on-delivery remittances.

## 5. Check

- Order count and totals in the file equal the Zid totals for the period; list
  any difference with its order numbers.
- With a connector posting orders: compare the accounting system's sales export
  for the period with the Zid orders by order number, and list orders missing
  from the books, present twice, or with different totals.

Done when the totals agree or every difference is listed by order number.

## Output

The import file (CSV or the target's template), a summary of orders, net sales,
VAT, shipping, discounts, returns and fees for the period, the payout
reconciliation, and every row that needs the merchant or accountant.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: catalog-bulk-edits
description: Change many Zid products at once. Use for price increases or decreases by percent or from a list, folding payment fees into prices, sale prices, publishing or hiding, categories, names, descriptions and SEO, images, market prices, duplicating or deleting products, or importing a product spreadsheet.
---

# Catalog bulk edits

Selects the products, shows every change before it happens, applies it with the
right tool for its size, and checks the result.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- Show the full change list (product, field, current → new) and apply it after
  the merchant agrees. When a manage tool answers `confirmation_required`,
  compare its plan with what the merchant approved: if they match, repeat the
  call with its `plan_id`; if not, show the plan and ask again.
- Change only the fields the merchant asked about. Rounding, products with
  variants, and items already on sale are the merchant's call: ask once, then
  apply the answer to every row.

## 1. Select the products

`zid_products.list_products` with `pageSize` 100, every page. Filters: `search`
(name, SKU or barcode), `categoryIds`, `priceMin` and `priceMax`, `isPublished`,
`inStock`, `hasDiscount`, `productClass`, `updatedFrom`. Details of one product:
`zid_products.get_product`. Variants of a product: `zid_catalog.list_variants`.
A product id that returns 404 was deleted: list again rather than retrying it.

Done when the merchant agrees with the list (count, plus a sample for long lists).

## 2. Work out the changes

- **Percent change**: new price = price × (1 + percent), rounded the way the
  merchant chose. A sale price stays below the price; recalculate it or flag the row.
- **Folding a payment fee into prices**: new price = price ÷ (1 − r), where r is
  the fee percentage as a fraction (2.5% → 0.025) from `zid_payments.get_fee_plan`
  or the merchant. Ask whether a fixed fee or VAT on the fee should be included.
- **From a list**: match rows to products by SKU, then barcode; list unmatched rows.
- **Text and SEO**: draft per product in the store's languages, keep facts from
  the current description, and state only specifications the product data or the merchant gives.

## 3. Apply

| Change | Tool |
| --- | --- |
| Name, price, quantity for many products | `zid_products_manage.bulk_update_products` with `products` (`id` and `sku` required, plus `name`, `price`, `quantity`, `isInfinite`) |
| Sale price, cost, description, SEO, keywords, barcode, weight, one product at a time | `zid_products_manage.update_product` with `productId` and only the changed fields |
| Publish or hide, VAT, shipping required (store owner only, up to 100 products per call) | `zid_catalog_manage.bulk_update_products` with `productIds` and `published`, `taxable` or `requiresShipping` |
| Move between categories (store owner only, up to 100 products per call) | `zid_catalog_manage.bulk_move_categories` with `productIds`, `oldCategoryId`, `newCategoryIds` |
| Add one product to several categories | `zid_products_manage.bulk_add_categories_to_product` with `productId` and `categoryIds` |
| Prices per market (stores selling in several markets) | `zid_settings.list_markets`, `zid_catalog.list_prices`, then `zid_catalog_manage.update_prices` with `priceUpdates` (up to 100 per call; `salePrice` null removes the sale) |
| Images | `zid_products_manage.add_product_image` (`productId`, `imageUrl` reachable from the internet, `altText`); order with `zid_products_manage.sort_product_images` |
| Duplicate, delete, restore | `zid_catalog_manage.bulk_duplicate_products`, `zid_catalog_manage.bulk_delete_products` (to the trash for 60 days), `zid_catalog_manage.restore_products` (returns hidden with zero stock) |

Large batches go in groups of 100, one group at a time.

## 4. Spreadsheet edits

For hundreds of rows or many fields at once:

1. `zid_catalog_manage.export_products` emails the merchant the catalog.
2. The merchant edits it and puts it at a public URL ending in `.csv` or `.xlsx`.
3. `zid_catalog_manage.import_products` with `fileUrl` and `importMode`:
   `update_all_fields` updates products matched by SKU with every column (blank
   cells are ignored unless `deleteEmptyFields` is true); `import_new` adds the
   rows as new products. `delete_old` deletes every current product first: use
   it only when the merchant asks for exactly that.
4. `zid_catalog.get_import_status` until it finishes; report the rows it rejected.

## 5. Verify

Read the changed products again (`zid_products.get_product`, or the list with
the same filters) and report changed, unchanged and failed rows with the reason.

Done when every product in the approved change list is reported as changed,
unchanged or failed.

## Output

The change table before approval; afterwards, counts of changed, skipped and
failed products and the failures with their reasons.

View saved version →

---
name: customer-sync
description: Move Zid customers between the store and a CRM, email or WhatsApp marketing tool, or loyalty system such as Mailchimp, Klaviyo, HubSpot, Zoho CRM, Brevo or a WhatsApp broadcast app. Use to build a contact file that carries marketing consent, segment customers by value or recency, tag Zid customers from an outside segment, or bring loyalty points in line with another system.
---

# Customer sync

Keeps customer records, segments and loyalty points consistent between Zid and
the merchant's marketing tools, without sending anyone a message they did not agree to.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- Consent travels with the contact. Zid's newsletter subscription is the email
  marketing consent; SMS and WhatsApp consent comes only from a recorded opt-in.
  Unknown consent is "not subscribed".
- Export only the fields the destination needs.
- Show the full change list and apply it after the merchant agrees. When a
  manage tool answers `confirmation_required`, compare its plan with what the
  merchant approved: if they match, repeat the call with its `plan_id`; if not,
  show the plan and ask again.
- Destination credentials (API keys, tokens) stay in that tool or the merchant's
  automation tool. Customer wallet balances are changed in the Zid dashboard.

## 1. Direction and owner

Settle which way the data flows (Zid → tool, tool → Zid, or both) and whether a
connector app already syncs it: `zid_account.list_installed_apps`, then
[references/destinations.md](references/destinations.md). With a connector in
place, compare the two sides and report differences instead of writing.

## 2. Read Zid customers

- `zid_customers.list_customers` with `perPage` 100, every page. Filters:
  `isNewsletterSubscriber`, `dateFrom` and `dateTo` (sign-up), `ordersCountCompare`
  with `ordersCountValue`, `tagIds`, `groupIds`, `customerChannels`.
- Value and recency: `zid_reports.customers_report` (lifetime value, orders and
  last order per customer; `page_size` up to 100), or `zid_reports.top_customers`.
- Large stores: `zid_customers_manage.export_customers` with `filters` emails the
  merchant a spreadsheet of customers' personal data; it needs the merchant's
  approval. Ask them to share only the columns the destination needs.

## 3. Segment

Default segments, unless the merchant defines their own:

| Segment | Rule |
| --- | --- |
| VIP | Top 10% by lifetime value, ordered in the last 90 days |
| Lapsed VIP | Top 10% by lifetime value, no order in 90 days |
| Repeat | 2 or more orders, ordered in the last 90 days |
| Lapsed | Ordered before, nothing in 90 days |
| New | First order in the last 30 days |
| Never ordered | Account without orders |

## 4. Zid → destination

Build one row per customer with the destination's headers from
[references/destinations.md](references/destinations.md):

- phone in international format (`+9665…`), email, first and last name;
- segment and tags as the destination's tags or properties;
- consent per channel: email from `isNewsletterSubscriber`; SMS and WhatsApp
  only where the merchant has a recorded opt-in.

Split the file at the destination's row limit.

Done when every customer in scope is either in the file or in the skipped list
with a reason.

## 5. Destination → Zid

- **Tags**: `zid_customers_manage.add_customer_tag` (`customerId`, `name`) adds
  one; `zid_customers_manage.set_customer_tags` (`customerId`, `tagNames`)
  replaces the customer's tags, so include the ones to keep.
- **Groups** are rule-based: `zid_customers_manage.create_customer_group` with
  `name` and `filters`. Members cannot be added one by one; tag them and build
  the group on the tag.
- **Email consent**: `zid_customers_manage.set_customer_marketing`
  (`customerId`, `subscribed`), only from a recorded opt-in or opt-out.
- **New or changed customers**: match by mobile, then email; create with
  `zid_customers_manage.create_customer` (`name`, `mobile`) or update with
  `zid_customers_manage.update_customer`.

## 6. Loyalty points

`zid_promotions.get_loyalty_status` confirms the program is on. For each
customer: `zid_promotions.get_customer_points`, the difference to the target
balance, then `zid_promotions_manage.adjust_customer_points` with `customerId`,
`direction` (`+` or `-`), `points` and a `reason` naming the source system.
`zid_promotions.get_customer_points_history` explains a balance.

## Output

Counts per segment, the contact file or the change list, then rows skipped with
the reason (no phone or email, no consent, no match, duplicate).

To keep the sync running daily, use the `zid-ops` skill.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: order-fulfillment
description: Run a Zid store's order fulfillment with its courier, fulfillment center or own drivers. Use for daily batches to preparing or ready, prep lists and waybills, tracking numbers and delivered updates, and reconciling a courier or fulfillment-center report against Zid orders, including cash on delivery.
---

# Order fulfillment

Moves orders through fulfillment and keeps Zid's order statuses in line with what
the courier or fulfillment center reports.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- Batches: show the full change list (a table when it covers more than a few
  orders) and apply it after the merchant agrees. When a manage tool answers
  `confirmation_required`, compare its plan with what the merchant approved: if
  they match, repeat the call with its `plan_id`; if not, show the plan and ask again.
- After writing, read the orders back and report what changed, what was skipped
  and what failed, with the reason.
- On a `429` answer, wait the seconds it names, then continue one call at a time.
- Courier credentials (API keys, passwords, tokens) stay in the courier's portal
  or the merchant's automation tool; when a step needs one, tell the merchant
  where to enter it.
- Refunds, payment status changes and shipment cancellations are done in the Zid dashboard.

## Order statuses

`new` → `preparing` → `ready` → `indelivery` → `delivered`. `cancelled` ends an
order before delivery. Stores can add custom statuses
(`zid_orders.list_custom_statuses`); bulk changes accept their codes.

## 1. Scope the run

Settle these before reading:

- **Orders**: statuses, date range, payment status and shipping method.
- **Carrier**: Zid Ship, a courier or fulfillment center with its own Zid app,
  or the merchant's drivers. `zid_account.list_installed_apps` shows the apps.
- **Who moves statuses**: look the carrier up in
  [references/carriers.md](references/carriers.md). Where the carrier's own
  connection moves statuses and adds tracking, this run reads and reconciles,
  so the two writers stay out of each other's way.
- **Pickup location**: `zid_inventory.list_locations`.

Done when you can state the filter, the carrier, who moves statuses, and the location.

## 2. Read the orders

`zid_orders.list_orders` with `status`, `dateFrom` and `dateTo` (YYYY-MM-DD),
`paymentStatus` and `perPage` 100, every page. For items and addresses call
`zid_orders.get_order`; for the warehouse that fulfils each line call
`zid_orders.get_fulfillment_inventories`.

Prepaid orders ship once paid; cash-on-delivery orders are collected at the
door. Put any other order (unpaid prepaid, missing address) on hold with the reason.

## 3. Move a batch

- **What `ready` sets off**: with Zid Ship, moving an order to `ready` sends the
  request to the courier and issues the waybill; Zid Ship runs on the store's
  wallet balance, so check it covers the batch. Some couriers' apps also book a
  pickup at `ready`. Say this in the change list before the merchant approves a
  move to `ready`.
- **Many orders**: `zid_orders_manage.bulk_set_order_status` with `orderIds` (up
  to 500) and `status`. Moving to `ready` can need `inventoryAddressId` (the
  pickup location) and `packagesCount` (1 to 99); add them when the call asks.
  It returns a `batchId`: read each order's result with
  `zid_orders.get_bulk_action_status` and report failures one by one. Where bulk
  changes are not available for the store, use
  `zid_orders_manage.update_order_status` per order.
- **Shipped with tracking**: `zid_orders_manage.update_order_status` with
  `orderId`, `orderStatus` `indelivery`, `trackingNumber`, `trackingUrl`, and
  `waybillUrl` when the merchant has one.
- **Delivered**: the same action with `orderStatus` `delivered`.
- **Notes for the team**: `zid_orders_manage.add_order_comment` (1 to 255
  characters); a batch label: `zid_orders_manage.add_order_tag`.

Cancel or return an order only when the merchant asks for that specific order.

## 4. Prep lists and waybills

- **Prep list emailed by Zid**: `zid_orders_manage.export_prep_list` with
  `statuses`, `dateFrom` and `dateTo`. It covers every order matching the
  filters.
- **Prep list in chat**: from step 2, one row per SKU with the total quantity,
  then the lines of each order.
- **Waybills**: `zid_shipping.get_waybills` with up to 100 `orderIds`, for any
  carrier (`includeInvoice` true adds the invoice). Where bulk printing is not
  available, call it once per order.

## 5. Reconcile with the carrier

1. Get the carrier's view: the report the merchant uploads (where to export it:
   [references/carriers.md](references/carriers.md)), or for Zid Ship
   `zid_shipping.list_shipments` (`dateFrom` and `dateTo` together, `pageSize`
   up to 100; filter codes from `zid_shipping.list_shipment_filters`),
   `zid_shipping.track_shipment` by `orderId`, and the cash couriers collected in
   `zid_shipping.list_cod_collected`.
2. Find the report's order-number and tracking-number columns by matching their
   values against the Zid orders, not by the header names, and map its statuses
   with the status map in [references/carriers.md](references/carriers.md).
3. Match each shipment to an order by order number, then by tracking number.
4. Put every order in scope in exactly one class:
   - matched: statuses agree;
   - not booked: in Zid, missing from the carrier;
   - unknown: with the carrier, missing from Zid;
   - behind: the carrier is further along than Zid (for example delivered while Zid shows `indelivery`);
   - exception: the carrier reports a failed delivery, return, refusal, damage or loss;
   - cash mismatch: collected amount differs from the order total in the same currency;
   - stuck: no carrier update for longer than the merchant's limit (default 3 days).
5. Offer the status updates for the behind class as one batch (step 3). Leave
   exception orders at their last true status and list them for the merchant;
   offer a custom status when the store has one for returns or failed deliveries.

Done when every order in scope sits in one class and the counts add up to the total.

## Output

- **Batch**: counts per status before and after, then failures with the reason.
- **Reconciliation**: a table of order, tracking number, Zid status, carrier
  status, expected cash, collected cash and class, followed by the counts per
  class.

To run this every day without a chat, use the `zid-ops` skill for a scheduled
job, or the `zid-api` skill to build an app that reacts to order events.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: reviews-and-questions
description: Run a Zid store's review and product-question desk. Use to triage pending product or store reviews, draft and post replies, approve or mark spam, answer customers' product questions, set up review requests after orders, or summarize what customers praise and complain about.
---

# Reviews and questions

Keeps reviews moderated and questions answered, in the customer's language, and
turns what customers say into something the merchant can act on.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- Replies are public. Thank the customer by name, address their point, and for a
  complaint offer a next step within the store's stated policy. Keep replies to
  what the store already offers, and keep personal details out of them.
- Approve genuine reviews, fair negative ones included. Mark obvious spam as
  `spam`. Delete only when the merchant asks for that review.
- Show the replies and moderation decisions first and post them after the
  merchant agrees. When a manage tool answers `confirmation_required`, compare
  its plan with what the merchant approved: if they match, repeat the call with
  its `plan_id`; if not, show the plan and ask again.

## 1. Reviews

1. `zid_products.count_reviews_by_status` for `pending` (and other statuses the
   merchant cares about), then `zid_products.list_reviews` with `status`,
   `dateFrom`, `dateTo` and `pageSize` 100, every page, until the count matches. `reviewType` `store` reads ratings of the store itself.
2. Draft one reply per review and a decision: approve, reject (abusive or off
   topic), or spam.
3. After approval, one review at a time: `zid_products_manage.update_review_status`
   (`reviewId`, `status`) and `zid_products_manage.reply_to_review`
   (`reviewId`, `text`). `zid_products_manage.update_all_review_status` changes
   every review at once: only when the merchant asks for exactly that.

## 2. Questions

Questions are read per product: `zid_products.list_questions` with `productId`.
Cover the products the merchant names, or the best sellers from
`zid_reports.top_products`. For each unanswered question:

1. `zid_products.get_product` for the facts; answer only from them or from what
   the merchant tells you.
2. After approval: `zid_products_manage.create_answer` (`productId`,
   `questionId`, `answer`), then `zid_products_manage.update_question_publishing`
   with `isPublished` true when the merchant wants it shown.

## 3. Settings

- `zid_campaigns.get_review_settings`: the review request customers get after an
  order (email, SMS, WhatsApp, delay), merchant alerts, editing, and auto-approval.
  Change it with `zid_campaigns_manage.set_review_settings` when the merchant
  asks (for example `autoApproveEnabled` with `autoApproveMinimumRating` 4).
- `zid_campaigns.get_question_settings`: who is emailed about new questions and
  answers.

## Output

Done when every review and question in scope is accounted for, and every
approved reply, status change or answer is posted and read back, or listed with
the reason it is pending.

A table of review or question, rating, product, proposed reply and decision;
after posting, what was posted and changed. End with the recurring themes: the
products praised, the complaints that repeat (sizing, delivery time, packaging),
and the product pages or fulfillment steps they point to.

To run the desk daily, use the `zid-ops` skill.

View saved version →

---
name: sales-report
description: Report a Zid store's sales and profit for any period. Use for a daily brief, a period comparison, a profit and loss estimate, best sellers, a breakdown by channel, city or payment method, or a report across several stores.
---

# Sales report

Answers "how did the store do" with numbers the merchant can check, and says
where each number came from.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- Read only. This skill changes nothing in the store.
- Every figure names its source (report or orders) and period. Estimates are
  labelled as estimates, with what they leave out.
- Amounts are in the store currency; dates are `YYYY-MM-DD`, and report periods
  resolve in Asia/Riyadh.

## 1. Settle the question

Period, comparison (previous period, same weekday last week, same month last
year), and the figures wanted: sales and orders, profit, products, channels,
customers. For a daily brief, default to yesterday against the same weekday a
week earlier.

## 2. Read the numbers

| Figure | Read |
| --- | --- |
| Headline totals: sales, orders, sessions, conversion | `zid_reports.sales_summary` with `period` (`yesterday`, `last_7_days`, `this_month`, `last_month` …) or `date_from` and `date_to`; `compare` true adds the previous period |
| Revenue, discounts, shipping, tax, cost of goods, margin, returns | `zid_reports.sales_report`; `components` breaks it down by `periods`, `channel`, `location`, `products`, `category`, `coupons`, `city`, `payment_methods` and more; `peak` finds the busiest weekday or hour |
| Best sellers | `zid_reports.top_products`, or `zid_reports.products_performance` for one row per product |
| Today, as it happens | `zid_reports.live_sales` |
| How current the data is | `zid_reports.data_freshness` |

**When the store has no analytics access**, the reports answer that analytics is
not available. Then:

1. `zid_orders.list_orders` with `dateFrom` and `dateTo`, `perPage` 100, every page.
2. Leave out `cancelled` orders and orders whose payment failed; count the rest.
3. Total the order amounts, discounts, shipping and VAT, and say the figures were
   computed from orders. `zid_reports.live_sales` still works for today.

## 3. Profit and loss

Reports give gross margin as a percentage, not profit. Build profit as:

| Line | Source |
| --- | --- |
| Net sales | `zid_reports.sales_report` (or the order totals), after discounts and returns, without VAT |
| − Cost of goods | `cogs` in `zid_reports.sales_report`; it needs a cost on each product. Name the best sellers without a cost and leave them out of the estimate |
| − Payment fees | `zid_payments.get_account_statement` for ZidPay, or the rates in `zid_payments.get_fee_plan` × card sales |
| − Shipping costs | `zid_shipping.list_shipping_charges` for Zid Ship labels and fees; other carriers from the merchant's invoice |
| − Other costs | Ads, salaries, rent: only what the merchant provides |
| = Profit (estimate) | Show each line, so the merchant can correct one |

## 4. Several stores

Each store has its own connection. Report each store separately, then a total
row, converting currencies only at the merchant's exchange rate.

## Output

- **Daily brief**: sales, orders, average order value and conversion against the
  comparison, with the change in percent; top 5 products; one line on anything
  unusual (a sales drop over 20%, a product that stopped selling, a spike in
  returns); and orders waiting in `new` for more than a day.
- **Period report**: the table of figures with sources, the breakdown asked for,
  then two or three observations backed by the numbers.
- **P&L**: the line table above with the estimate flagged and the missing costs listed.

Done when every figure names its source and period, and every comparison shows both values.

To send the brief every morning, use the `zid-ops` skill for scheduled jobs.

View saved version →

---
name: stock-sync
description: Keep a Zid store's stock in line with an ERP, POS, warehouse system or spreadsheet such as Rewaa, Foodics, Odoo, Zoho Inventory, Qoyod, Daftra or Business Central. Use to compare quantities by SKU and location, apply a stock file or physical count to Zid, record received or damaged stock, or check why two systems disagree.
---

# Stock sync

Compares the stock in another system with Zid's, product by product and location
by location, then brings Zid in line with whichever system the merchant names as
the source of truth.

## Ground rules

- The merchant's explicit instructions take precedence over this skill.
- One system owns each quantity. Before writing, find out whether a connector
  already pushes stock into Zid (step 1). Writing beside a connector makes the
  two overwrite each other, so with one in place this skill reports and leaves
  the fixing to the owning system.
- Show the full change list and apply it after the merchant agrees. When a
  manage tool answers `confirmation_required`, compare its plan with what the
  merchant approved: if they match, repeat the call with its `plan_id`; if not,
  show the plan and ask again.
- Other systems' credentials (API keys, passwords, tokens) stay in that system or
  in the merchant's automation tool. Work from the files the merchant shares.

## 1. Find the source and the owner

1. Ask which system holds the true stock, or read it from the file the merchant shares.
2. `zid_account.list_installed_apps` shows whether that system's connector is
   installed. Look the system up in [references/systems.md](references/systems.md)
   for which way its connector moves stock and how to export its stock.
3. Locations: `zid_inventory.list_locations`. Agree which source warehouse or
   branch maps to which Zid location; one source location can feed only one Zid location.

Done when you can name the owner of the quantities and the location mapping.

## 2. Read both sides

- **Source**: the merchant's export. Find the SKU, barcode, quantity and location
  columns by matching values against Zid's SKUs, not by header names. Read
  identifiers as text so leading zeros survive. Note whether the quantity is an
  ending balance or a movement (+/-); the references say which for each system.
- **Zid**: `zid_products.list_products` with `pageSize` 100 and every page (or
  `search` for one SKU or barcode; `locationIds` limits it to the mapped
  locations). For each product in scope, `zid_products.list_stock` with
  `productId` gives its quantity at each location; for a product with variants,
  `zid_catalog.list_variants` with `productId` and `locationIds` gives each
  variant's stock. For catalogs of more than a few hundred products,
  `zid_catalog_manage.export_products` with `locationIds` emails the merchant the
  dashboard's product export; ask them to share it and compare the two files.

## 3. Match and compare

Match each source row to a Zid product or variant by SKU, then by barcode. Map
each variant to its own row. Convert cartons or
packs to the unit Zid sells before comparing.

Put each row in one class:

- equal;
- differs: show Zid quantity, source quantity and the difference;
- unlimited in Zid: the product does not track stock; changing it is a separate decision;
- bundle: its stock comes from its products, so leave it out;
- only in source / only in Zid: list them, with likely matches when a SKU differs only by spacing or case;
- invalid: negative, blank or non-numeric quantity.

Done when every source row and every tracked Zid product at the mapped locations
sits in one class and the counts add up.

## 4. Apply

Pick the path that matches what the numbers mean:

| The numbers are | Use | Notes |
| --- | --- | --- |
| A physical count | `zid_inventory_manage.create_stock_count` with `locationId`, `name` and `start` true counts every tracked product at the location. For some products only, create it with `isPartial` true, add them with `zid_inventory_manage.update_stock_count` (`stockCountId`, `productIds`), then start it with `countStatus` `in_progress`. Enter counts with `zid_inventory_manage.record_counted_quantities` (`stockCountId`, `counts` of `productId` and `count`, up to 500 per call) and apply with `zid_inventory_manage.complete_stock_count` | Applies counted minus expected, so sales made during the count are kept. Completing cannot be undone. |
| Exact balances from the source | `zid_inventory_manage.update_location_stock` with `locationId` and `products` (`productId`, `availableQuantity`, `isInfinite`) | Replaces the quantities. Orders placed between reading the source and writing are overwritten, so run it right after the export. |
| One product across locations | `zid_products_manage.bulk_update_stock` with `productId` and `stocks` (`location`, `availableQuantity`, `isInfinite`) | |
| Movements: stock received, damaged, returned | `zid_products_manage.adjust_stock` with `productId`, `locationId`, `quantityChange` (signed, not 0) and `adjustmentReason` | Refuses to go below 0 and refuses unlimited stock. |

## 5. Verify

Read `zid_products.list_stock` with `productId` again for the changed products and report the counts
per class before and after. `zid_inventory.list_stock_history` (last 60 days, by
`locationId` or `productId`) shows who or what changed a quantity, which explains
most "the numbers keep drifting" questions.

## Output

A table of SKU, product, location, Zid quantity, source quantity, difference and
class, followed by counts per class, the changes applied, and the rows that need
the merchant (unmatched SKUs, bundles, unlimited stock, invalid quantities).

To repeat the sync on a schedule, use the `zid-ops` skill.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: zid-api
description: Answer Zid developer questions from the live docs at docs.zid.sa. Use when building a Zid app or integration, calling the Zid Merchant API, setting up Zid OAuth, scopes or webhooks, or reading a Zid API error.
---

# Zid API

Partners and merchants build on Zid through its public developer platform, and
its documentation at `https://docs.zid.sa` is the only source for how that
works. The docs change, so this skill holds no API facts of its own: it is the
procedure for finding them. Running store work through the Zid MCP tools, or on
a schedule, is the `zid-ops` skill.

## Ground rules

- The user's explicit instructions take precedence over this skill.
- Every endpoint, header, scope, parameter, limit, status code and event name in
  an answer comes from a docs.zid.sa page fetched in this conversation, and the
  answer links that page.
- Answer with documented endpoints only. When the user names one the docs do not
  list (seen in a browser, another tool or another integration), say it is not
  in the Zid developer docs.
- Secrets stay out of chat: client secrets, tokens and webhook credentials go
  into the app's secret store. In examples, write them as placeholders such as
  `<CLIENT_SECRET>`.

## Look it up

1. Fetch the index, `https://docs.zid.sa/llms.txt`. Each line holds a section
   path (such as `Merchant APIs > Orders`), a page title and the page's `.md`
   URL. Done when the index is loaded; if it cannot be fetched, say so and ask
   the user for the page instead of answering from memory.
2. Pick the pages. Every question needs the concept pages it touches (for
   example `Authorization`, `Rate Limiting`, `Responses`, the webhooks
   `Overview`) and the endpoint page for each call. Done when each part of the
   question has a page, or is noted as not in the index.
3. Fetch each page's `.md` URL. Endpoint pages carry the OpenAPI spec: server,
   method, path, headers, parameters, request body and responses. Some also
   list the scopes; when a page names none, say the scope is not stated there.
4. Answer from the fetched text: exact names as written, a link per page, code
   with secrets as placeholders. Where two pages disagree, give both with their
   links and say which one is the API reference.

Done when every fact in the answer links to a page fetched in step 3, and every
gap is named as not documented.

## Errors

For an error, ask for the status code and the full response body first, then
fetch `Responses` and, for sign-in and token errors, `OAuth Errors &
Troubleshooting`. Match the exact error text to the page; when it is not there,
say so and give the request and response the user would send to Zid.

View saved version →

---
name: zid-ops
description: Connect and automate a Zid store. Use to connect an AI agent, n8n, Make or a script to the Zid MCP server, schedule a recurring store job, or fix a Zid MCP tool error in a saved workflow.
---

# Zid ops

Running a Zid store with automations: connecting clients to the Zid MCP server
and scheduling store jobs. The other Zid skills describe the store work; this
one covers how to run it without a chat. Building an app on the Merchant API,
OAuth or webhooks is the `zid-api` skill.

## Ground rules

- The user's explicit instructions take precedence over this skill.
- Secrets stay out of chat: the personal MCP URL and any tool credentials go
  straight into the client's or automation tool's credential settings. In
  examples, write them as placeholders such as `<MCP_URL>`.
- One writer per field. Before automating a write, check whether an installed app
  already writes it (`zid_account.list_installed_apps`) and agree with the
  merchant which one owns it.

## Pick the topic

| Topic | Use it when | Read |
| --- | --- | --- |
| MCP connections | Connecting Claude, Cursor, Codex, n8n, Make or a script to the store's tools; tool errors and statuses | [references/mcp.md](references/mcp.md) |
| Scheduled jobs | A store task should run every day or on an event, without someone in the chat | [references/jobs.md](references/jobs.md) |

Read the topic's reference before writing anything for it; a job usually needs both.

## Steps

1. Pick the topic and read its reference.
2. Settle the inputs: which store, which client or tool, what triggers the run,
   what it reads and what it may change.
3. Produce the artifact: client configuration or workflow steps, with secrets as placeholders.
4. Prove it with a read before any write: call one named read action, such as
   `zid_store.get_context` or `zid_orders.list_orders`.
5. Hand over: where each secret goes, how to rotate it, and how to tell when the
   automation fails.

Done when the client or job has run one read successfully and the merchant knows
where its secret lives.

## Common failures

Answers such as `invalid_arguments`, `confirmation_required`, the stale-plan
statuses and `429` are covered in [references/mcp.md](references/mcp.md), under
"How the tools behave".

| Symptom | Cause | Fix |
| --- | --- | --- |
| Unknown tool in a saved workflow | The workflow uses a renamed tool | Replace the step with the tool and action the matching Zid skill names |
| A skill's tool is not available | The URL loads only some areas | Add the area to `?toolsets=` ([references/mcp.md](references/mcp.md)) |
| The URL stopped working | It was rotated | Copy the new URL from the Zid AI Connector app into every client |

Referenced files: 2 — file references are metadata, not package contents.