MATJRAH DEVELOPERS + APPS CENTER

Publish your
Shipping App on Matjrah.

Shipping always starts with a Shipping App. Create it in the Developers Center, declare the carrier services, receive signed shipment jobs, return the AWB and label, then push tracking, cancellation and return states.

Start in the Developers Center Meet the Partnerships team

Integration support: dev@matjrah.com · ERP integration guide · API reference

THE MATJRAH PLATFORM

One shipping connection across the merchant journey.

Matjrah turns shipping into an installable merchant product—not a loose API credential. The carrier creates and certifies the Shipping App in the Developers Center; merchants find and install the approved app through the Apps Center.

Every merchant approves the app independently. Tokens, shipment records and Webhook deliveries remain isolated by installation and can be revoked without sharing the merchant’s master credentials.

3,500+merchant stores use Matjrah

One app pathCreate a Shipping App in the Developers Center

Per-store installsIndependent scopes, token and shipment ownership

Forward + returnOne shipment contract supports both directions

Courier network Shipping aggregator 3PL provider Last-mile fleet

These are supported partner models, not claims of a ready-made integration with a particular carrier.

SANDBOX CHECKPOINT

One signed shipment event, accepted durably.

Self-service Sandbox proves installation, HMAC verification and delivery of shipment.creating. AWB attachment, tracking, cancellation and tenant isolation must be certified on a provisioned active test store. Understand the environments ↗

BEFORE YOU WRITE CODE

Prepare the carrier side first.

A practical integration starts with three concrete inputs. Have them ready before creating handlers or mapping payloads.

01 / CARRIER API

Prove create, label and cancel

Confirm the carrier sandbox credentials and exact requests for shipment creation, AWB/label retrieval, tracking and cancellation.

Runtime workflow →

02 / HTTPS WEBHOOK

Accept work durably

Expose one HTTPS endpoint that verifies the raw-body signature, stores the event and sends slow carrier work to a queue.

Webhook contract →

03 / MAPPING SHEET

Map services and states

List every carrier service code, coverage rule, COD capability and tracking state beside the documented Matjrah value.

Certification scope →

THE COMPLETE PRODUCT — NOT ONLY AN ENDPOINT

Build the first working shipment in this order.

Complete one vertical slice before expanding services: app installation, signed event, durable claim, carrier request, AWB/label response, then lifecycle updates.

01RegisterCreate the partner account for your integration team.
02Create the appChoose Shipping and add the HTTPS Webhook URL.
03Declare servicesAdd carrier codes, coverage, rates, periods and COD support.
04Prove deliveryVerify and deduplicate the signed Sandbox event.
05Certify the cycleAttach AWB, push tracking and test cancellation.
06Submit and publishComplete review, then let merchants install independently.

CREATE THE SHIPPING APP

Configure the portal and backend together.

Shipping has one entry path: an approved Shipping App. API and Webhooks operate that installed app; they are not standalone dashboard credentials.

DEVELOPERS CENTERConfiguration

Create and describe the Shipping App

Set up the product merchants will install and the services it exposes.

Choose the Shipping app type
Add app name, logo, support and policy links
Register the HTTPS Webhook URL
Declare carrier codes, coverage, defaults, periods and COD

Create the Shipping App ↗

YOUR BACKENDRuntime

Build one safe shipment worker

Keep the Webhook response fast and move carrier work behind a durable claim.

Verify HMAC against the exact raw body
Store each installation token separately
Deduplicate by request and shipment IDs
Map the carrier result and attach AWB/label idempotently

Open the Shipping API reference ↗

ALREADY BUILT FOR SALLA?

Keep the carrier logic.
Replace the platform adapter.

If your Salla app already creates AWBs, labels and tracking updates, do not rebuild the carrier integration. Preserve that proven layer and add a Matjrah Shipping App adapter for installation, signed events, shipment ownership and callbacks.

Download the practical migration Skill Read the Shipping migration contract ↗

REUSE

Your proven shipping core

Carrier authentication and API client
AWB and label generation
Tracking normalization
Cancellation and return rules
Queues, monitoring and support tooling

REPLACE

The commerce-platform edge

Salla OAuth → signed app.installed
Salla token lifecycle → per-store ait_…
Salla event verifier → raw-body Matjrah HMAC
Salla shipment payload → shipment.creating
Salla callbacks → Matjrah attach, track and cancel

FOCUSED PROTOTYPEOne working shipment in 24 hours

A practical target when the existing Salla app and carrier API already work—not a production or certification guarantee.

01Inventory the Salla adapter without editing
02Add Matjrah installation + signature verification
03Map one shipment.creating fixture
04Return one AWB and label idempotently

What the AI agent must leave behind: inventory.md, mapping.md, gaps.md, test-plan.md, a separate Matjrah adapter, and tests for invalid signatures, duplicate delivery, tenant isolation and retry safety.

Never send production tokens, recipient data or real payloads to an AI tool unless your organization has approved that tool and its data controls.

THE SHIPMENT RUNTIME

Receive the job, return the shipping truth.

API and Webhooks are the runtime of an approved, installed Shipping App—not a separate integration path. Verify the exact raw Webhook body, persist request_id and shipment_id, and use only that installation's token.

01 / MANIFEST

Services and defaults

Declare carrier codes, countries, zones, default cost, delivery period and capabilities such as COD.

02 / WEBHOOK

`shipment.creating`

Receive order, recipient, items, weight, COD amount and direction: forward | return in the signed event.

03 / AWB + LABEL

`PUT /v1/shipments/{id}`

Attach the AWB, tracking number, stable tracking link and optional label URL to the exact shipment.

04 / LIFECYCLE

Track or cancel

Push picked-up, in-transit, out-for-delivery, delivered, returned or failed states; cancel with the dedicated endpoint.

Open the Shipping API reference ↗Bearer ait_… · 120 requests/minute/installation

WHAT TO CERTIFY

The complete operational cycle

A logo and a successful sample Webhook are not enough. Review covers the real installed-store lifecycle and failure behavior.

Forward shipmentsReturn shipmentsAWB and label deliveryStable tracking linksCOD amount handlingZones and default ratesCancellation and retry safetyTenant-isolated credentials

REVIEW READINESS

A Shipping App merchants can operate

Certification starts with shipment ownership and failure recovery, not listing copy.

Signature verificationVerify HMAC against the exact raw body before parsing.
Durable deduplicationDo not create a second carrier shipment for a repeated request_id or shipment_id.
Tenant isolationNever mix install tokens, shipment queues, labels or logs across stores.
Complete callbacksReturn AWB and label, then push tracking, cancellation and terminal states.
Actionable monitoringCorrelate errors to the installation and shipment without exposing secrets or recipient data.

CREATE YOUR SHIPPING APP

Package your shipping service for Matjrah merchants.

Start by creating a Shipping App in the Developers Center. If you represent a courier, shipping aggregator or 3PL provider and need technical or commercial alignment, schedule a conversation. For app integration support, email dev@matjrah.com.

Create your shipping app Schedule a 30-minute call

ERP waybills, returns and exchanges

On provisioned stores enabled for this contract, normal ERP apps can register an already-booked forward waybill with PUT /api/app-center/v1/orders/{id}/fulfillment (orders.write and a unique Idempotency-Key). Read it with GET on the same path (orders.read). Send awb_number and optional tracking_number, HTTPS tracking_link and public PDF label_url. Registration changes no order status, payment or stock and does not book a courier. Existing or differently owned waybills return 409; the owning installation may update tracking or repair a label with the same AWB and a fresh key.

ERP apps with returns.read receive return.created and supported return.updated events. Enabled return responses expose request_kind (return, exchange, mixed) and return_context: return_id, original_order_id, exchange_id, replacement_order_id, exchange_state, returned_items, replacement_items and related_shipments. Order reads/events expose return_contexts; use is_replacement to identify a replacement order. Store-configured action IDs are not universal enums.

A Return/Exchange dropdown choice does not automatically book shipments. The merchant selects replacement items, satisfies the credit/payment requirements and releases the replacement order, then explicitly requests the reverse and replacement forward shipments. A Shipping-only app receives shipment.creating with direction return or forward and the shared return_context when linked; it does not receive general return events without returns.read. Attach and track each leg separately. GET /shipments/{id} refreshes the related pair after the other leg exists.

App Center shipment_id is unique across stores within one environment, and access remains installation-scoped. Internal merchant shipment IDs, order_id, return_id and exchange_id are store-local; index them with store_id. Read the API reference for request examples, PDF limits, safe retries and availability.