orderCreate // Deferred Payment / SalesAgreement

GraphQL Admin API Troubleshooting
1

Hey All,

I am creating a new internal API workflow, and wanted to delay payment until later on the order (like draft orders).

Wondering how I would do this via GraphQL mutation? API version is 2025-04

Screenshot 2025-04-28 at 12.48.33 pm
Screenshot 2025-04-28 at 12.48.33 pm1074×492 29.5 KB

** Update

With some digging it seems to be called SalesAgreement

Cheers

Chris

1 Like
2

Good find @ChrisBradley

For anyone else that’s looking, here’s the link to the docs

3

thanks @KyleG-Shopify

Out of curiosity how do we create a salesagreement for a draft order via. graphQL? I looked at the createOrder mutation and cant see it there.

4

Hey Chris,

If you’re adding an agreement to a draft order you can use the payment terms input DraftOrderInput - GraphQL Admin

You can query the payment terms to get the details of the different templates:

{
    paymentTermsTemplates {
        description
        dueInDays
        id
        name
        paymentTermsType
        translatedName
    }
}
5

@KyleG-Shopify interesting. so we can add this to a draft order but not a normal order with orderCreate? Or is paymentTermsTemplates allowed in orderCreate as well.

Can you convert orders from Draft > Confirmed via graphQL? might be suitable if we can.

6

The orderCreate input doesn’t have this field. Typically orderCreate is used for a record of an order that is placed outside of the store so it couldn’t be put in to a state with active payment terms. If the order had terms, you could use one of the custom fields to add that, or set the transactions as pending if it hasn’t been paid yet.

Draft orders would be best for this. The draftOrderComplete mutation converts a draft order in to an order with the terms and pending payment. You can then use the orderCreateManualPayment mutation to mark the order as paid.

Let me know if that will work

7

got it, is there a reason why orderCreate doesnt allow this?I guess from my point of view, we do a fair bit of marketplace orders (where they are net 30 accounts), and instead of a draftOrderInput then draftOrderComplete, it would be much easier to do this via a createOrder. currently we have to post a manual payment then rec in quickbooks. whereas if we could do this it would save that process step.

8

I can see how it would be useful on orderCreate to have that record more inline with draft orders. Can you share a little additional context on your flow where orderCreate would be easier? I’ll pass that on to our product teams.

9

Sure.

We currently have several marketplace clients who have net30/net14 terms, so we have them set up as wholesale customers on B2B (as we are plus) with payment terms.

Currently:

Webhook > IPaaS > DraftOrder > Order

  • IPaaS is our server that gets the payload and processes it to allow the payload to be DraftOrder
  • DraftOrderCreate Is the order we need to create to get the defered payments.
  • Order is the mutation we need do to convert from draft to order. (we would catch the response from DraftOrderCreate and then send a second call)

The problem with this is that it makes managing draft order (that we also use for actual draft order) really hard as we effectively have these draft orders sitting there after the fact (as that is the draft order process).

Ideally:
Webhook > IPaaS > OrderCreate

  • Single Payload to OrderCreate with defered payment within

This would reduced the amount of records by 1x (as we would no longer need to create draft orders for these), as well as reduce our API usage by 1x (as we would no longer need to have the second call for the mutation to convert the draft to an actual order). Apart from that, it will make it easier to manage draft orders as we would have less helper orders (ones that are created just to facilitate the Defered Payment).

I think additionally, it would help standardise payment options across all orders irregardless of source (draft / order)

10

Thanks for those details Chris. I’ve passed that on to our product teams to consider for future updates. :slight_smile:

11

No problem, don’t hesitate to DM me if they need some more context at all.

1 Like