orderCreate

Type: Mutation

Creates an order for your seller account and returns the payment link the buyer uses to pay. This is step 1 of the Integration flow.

The order is linked to the seller wallet of your API token. The buyer is identified by the phone number in shipping.phoneNumber (or by customerId if you already know their Sevi wallet); a buyer who is not on Sevi yet is onboarded on the payment page.

Request

mutation OrderCreate($input: OrderInput!) {
  orderCreate(input: $input) {
    order {
      id
      referenceNumber
      platformReference
      status
      paymentStatus
      amount
      currency
      paymentLink
    }
  }
}

{
  "input": {
    "platformReference": "INV-1001",
    "currency": "KES",
    "returnURL": "https://shop.com/sevi/return?invoice=INV-1001",
    "items": [
      {
        "name": "Maize flour 2kg",
        "description": "Maize flour 2kg bale",
        "currency": "KES",
        "unitPrice": 2500,
        "quantity": 2,
        "sku": "MF-2KG"
      }
    ],
    "shipping": {
      "firstName": "Jane",
      "lastName": "Wanjiku",
      "company": "Jane's Duka",
      "address1": "Kenyatta Avenue 12",
      "city": "Nairobi",
      "country": "KE",
      "phoneNumber": "+254712345678"
    },
    "billing": {
      "firstName": "Jane",
      "lastName": "Wanjiku",
      "address1": "Kenyatta Avenue 12",
      "city": "Nairobi",
      "country": "KE",
      "phoneNumber": "+254712345678"
    }
  }
}

Input fields

Order (OrderInput)

Field	Required	Description
items	yes	Line items, see below. The order amount is the sum of unitPrice × quantity.
shipping	yes	Delivery details. shipping.phoneNumber identifies the buyer and receives the order/payment SMS.
billing	yes	Billing details.
platformReference	recommended	Your invoice / order number. Must be unique per order; it is returned on every webhook and can be used with orderSearch.
currency	no	KES or UGX. The order currency is taken from the items' currency; keep all items in one currency.
returnURL	no	Where the buyer is sent after a successful payment — see Return URL.
customerId	no	Buyer's Sevi wallet account, if you know it. Otherwise the phone number is used.
customerReference	no	Your own id for this buyer; shown back to you as customer.reference on webhooks.
platformId	no	Secondary reference shared between integration partners.
notes	no	Free text shown with the order.
discount, fixedVat, percentageVat	no	Amount adjustments.
invoiceURL	no	Link to your invoice PDF, shown to the buyer.
messaging	no	Set to false to stop Sevi from sending the buyer SMS/push messages about this order.

Leave the other fields (status, paymentStatus, paymentMethod, vendorId, …) empty — they are set by Sevi. The vendor is always the wallet of your API token.

Item (ItemInput)

Field	Required	Description
name	yes	Product name
description	yes	Product description
currency	yes	KES / UGX
unitPrice	yes	Price per unit
quantity	yes	Number of units
sku, barcode, platformId	no	Your product identifiers

Shipping / billing (ShippingInput, BillingInput)

Required: firstName, lastName, address1, city, country (ISO code, e.g. KE). Optional: company, address2, state, postcode, email, phoneNumber; shipping also accepts latitude, longitude, shippingType.

Response

{
  "data": {
    "orderCreate": {
      "order": {
        "id": "0b9f6f7e-5a8c-4a57-9a52-3c2f0e1d9a11",
        "referenceNumber": "D123456",
        "platformReference": "INV-1001",
        "status": "PENDING",
        "paymentStatus": "PENDING",
        "amount": 5000,
        "currency": "KES",
        "paymentLink": "https://p.sevi.io/D123456"
      }
    }
  }
}

Store:

• order.id — needed for orderDeliver and orderCancel.
• order.referenceNumber — Sevi's order number, shown to the buyer.
• order.paymentLink — send or show it to the buyer, see Payment link.

The response can also include paymentOptions (ways to pay now) and paymentProposals (credit options for this buyer) if you request those fields.

Errors

Message	Cause
an order with this reference already exists	platformReference was already used for another order
Customer account shouldn't be the same as vendor wallet	The buyer is your own wallet
Validation errors on items, shipping, billing	A required field is missing

Creating the same order twice within a short time (same buyer, same amount) returns the existing order instead of a duplicate.