Creating Orders with Custom Line Items

What you’ll learn

In this article you’ll learn how to create orders that include custom line items using the orderCreate mutation:

• What a custom line item is and when to use it
• The custom field on LineItemInput and its available attributes
• How to create an order with custom line items
• How to mix custom and catalogue line items in the same order
• Common errors and how to resolve them

Background

The standard orderCreate flow requires each line item to reference a variantId — a product variant that exists in the Marketplacer catalogue. This works well for marketplace orders where products are managed by sellers on the platform.

However, there are scenarios where an operator needs to create an order for a product that doesn’t exist in the Marketplacer catalogue. A common example is an operator who sells their own first-party products alongside third-party marketplace sellers, and wants to route all orders — regardless of product source — through Marketplacer to take advantage of unified payout management via MPay.

To support this, LineItemInput accepts a custom field as an alternative to variantId. Instead of referencing an existing variant, you supply the product details inline along with the seller who should receive the payout.

The custom field

The custom field accepts a CustomLineItemInput object with the following attributes:

Using orderCreate with custom line items

Invoice auto-splitting

When you use the top-level lineItems array on orderCreate, Marketplacer automatically groups line items into invoices by seller (and delivery type). This works the same way for custom line items — they are grouped by their explicit sellerId.

For standard (variant-based) line items the seller is derived from the variant’s advert. For custom line items you provide the seller explicitly via sellerId, so the same auto-splitting behaviour applies.

Example 1: Create an order with a single custom line item

mutation {
 orderCreate(
  input: {
   notifications: [EMAIL]
   order: {
    firstName: "Jane"
    surname: "Smith"
    phone: "0400000000"
    emailAddress: "jane@example.com"
    address: {
     address: "146 Buckhurst Street"
     city: "Melbourne"
     country: { code: "AU" }
     postcode: "3000"
     state: { name: "Victoria" }
    }
   }
   lineItems: [
    {
     custom: {
      sellerId: "U2VsbGVyLTEyMw=="
      advertName: "MPXL Gaming Headset"
      variantName: "Black"
      sku: "MPXL-GH-BLK"
      brandName: "MPXL"
      taxonName: "Electronics"
     }
     quantity: 1
     cost: { amount: 8995, tax: 817 }
     postage: { amount: 995, tax: 90 }
    }
   ]
  }
 ) {
  order {
   id
   legacyId
   totalCents
  }
  status
  errors {
   field
   messages
  }
 }
}

Example 2: Mix custom and catalogue line items in the same order

In this example the customer purchases both a catalogue product (referenced by variantId) and a custom line item (referenced via custom). Because these line items belong to different sellers, Marketplacer will automatically create two separate invoices — one per seller — ensuring that each party receives the correct payout.

mutation {
 orderCreate(
  input: {
   order: {
    firstName: "Jane"
    surname: "Smith"
    phone: "0400000000"
    emailAddress: "jane@example.com"
    address: {
     address: "146 Buckhurst Street"
     city: "Melbourne"
     country: { code: "AU" }
     postcode: "3000"
     state: { name: "Victoria" }
    }
   }
   lineItems: [
    {
     variantId: "VmFyaWFudC03MTM3"
     quantity: 2
     cost: { amount: 4999, tax: 454 }
     postage: { amount: 500, tax: 45 }
    }
    {
     custom: {
      sellerId: "U2VsbGVyLTEyMw=="
      advertName: "Exclusive Bundle"
      sku: "BUNDLE-001"
     }
     quantity: 1
     cost: { amount: 12900, tax: 1172 }
     postage: { amount: 0, tax: 0 }
    }
   ]
  }
 ) {
  order {
   id
   legacyId
   totalCents
   invoices {
    nodes {
     id
     totalCents
    }
   }
  }
  status
  errors {
   field
   messages
  }
 }
}

Common errors

The following errors may be returned in the errors field of the mutation response: