orderUpdate

Key Information

Use-Case

orderUpdate is used to update a finalized order - most commonly to progress its status (e.g. from payment_in_progress to complete, or to payment_failed), to merge in additional paymentGatewayDetails, to update buyer/billing details via attributes, or to manage the order’s MPay paymentReferences.

Further Points of Note

• orderId and status are always required, even if you are only updating paymentReferences or attributes - you must re-supply the order’s current (or new) status on every call.
• attributes lets you update buyer and billing details (name, email, phone, address, company name, message to seller, etc.) - see OrderUpdateInput for the full list of fields. Any field left out of attributes is unchanged.
• paymentGatewayDetails (a JSON object) is merged into the order’s existing payment gateway details rather than replacing them outright.
• paymentReferences, when supplied, fully replaces the order’s existing set of payment references for this call: any reference you omit from the array is deleted, any reference with a paymentReference key you already have will have its amount updated, and any new paymentReference key is created. If you leave the paymentReferences argument out entirely (null), the order’s existing payment references are left untouched.
• If MPay is enabled on your marketplace:
  • The sum of amount across the supplied paymentReferences must equal the order’s total, and paymentReference values must be unique within the array.
  • You cannot use orderUpdate to remove every payment reference from an order - at least one must remain at all times. To add or correct a reference, supply the full desired set; to replace one, include its replacement, not just its removal.
• If MPay is not enabled on your marketplace, paymentReferences must not be supplied at all.
• See the Automated Payouts (MPay) Integration Guide for the full payment references workflow.

Availability

• Operator API: Yes
• Seller API: No - sellers cannot update orders

Example

mutation updateAnOrder {
  orderUpdate(
    input: {
      orderId: "T3JkZXItODQ5Mzg="
      status: COMPLETE
      paymentReferences: [
        { paymentReference: "VISA_230226_2", amount: "20.00" }
      ]
    }
  ) {
    order {
      id
      legacyId
      status
      totalCents
    }
    errors {
      field
      messages
    }
  }
}

Arguments

Response

Returns OrderUpdateMutationPayload

Error Responses

Further Reading

• Automated Payouts (MPay) Integration Guide
• orderCreate
• Connected Integration Blueprint