Zoey REST API reference · Interactive version: apidocs.zoey.com

Orders

Orders: Bill (Invoices)

The Bill endpoint is available to Create an Invoice, Pay an Invoice, Get Invoice Details, Void an Invoice, Email Invoice PDF, Print Invoice PDF, or to Update an Invoice.

Attachments

Add

POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill/attachments

Example request body:

{
    "billId": 2809,
    "attachments": [
        {
            "file_name": "attachment_1.jpg",
            "file_mime_type": "image/png",
            "file_content": "iVBORw0KGgo..."
        }
    ]
}

Delete

DELETE https://container-url.zoeysite.com/api/rest/sales2/orders/bill/attachments

Example request body:

{
    "billId": 2810,
    "attachmentId": 29
}

Create

POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill

This endpoint creates an Invoice.
It can also create a Shipment for the invoiced Items.

Required Top-Level Parameters

Each of the following five (5) Parameters must be included in the correct order to properly make this API call.
If you are not sending data for one of these five (5) parameters, it should be included in the call with null value.

{
    "orderIncrementId": "100000024",
    "itemsQty": { "106537": 15 },
    "comment": null,
    "shipmentData": null,
    "extraData": { "send_email": 0, "due_date": "2023-09-19" }
}

Param Notes
orderIncrementId The increment ID of the order to create the invoice for.
itemsQty Array of objects. Object key is itemId and the value is qty. (ex. [{ "311": "2" }] Would bill 2 of order item 311) The Order Item ID that is used will always be the Parent ID in the event of a Configurable/Grouped/Bundled product.
Packaged Items will use their packaged qty. So if 2 cases of 15 were ordered. The ordered_qty will be 30 but the qty entered would be 2. This can be ignored by using the ignore_qty_multiplier flag in extraData.
comment Message to send to create on invoice for customer to see. (Optional)
shipmentData Used when shipping at the same time as invoicing. Array of ShipmentData OR true. When set to true it will ship all items/quantities that are being invoiced.
extraData Used to set custom totals. Uses ExtraData

ShipmentData

Param Notes
ship_items Object key is itemId and the value is qty. (ex. { "311": "2", "312": "1" } Would ship 2 of order item 311 and 1 of order item 312) The Order Item ID that is used will always be the Parent ID in the event of a Configurable/Grouped/Bundled product. (Optional, will use all items/quantities that are being invoiced if not provided.)
ship_immediately (Boolean) If set to true then the shipment will be created at the time of the request. If set to false it will configure the shipment to be created when the bill is paid and the invoice is created. (Default: false)
tracking Array of TrackingData
send_email Accepts a value of 0 or 1. Will send email for new shipment if set to 1. Defaults to 1.

TrackingData

Param Notes
carrier_code Code for the shipment carrier used for tracking. A list is available using the Get Carriers method.
number Tracking Number
title Tracking Carrier title

ExtraData

Param Notes
totals_info Object used to set custom totals for invoice. Array of ExtraDataTotal
ignore_qty_multiplier This is used to allow the qty_ordered to be directly entered instead of the packaged qty for items that use packaging.
due_date This is used to set the due date on the invoice. Do not set this value if setting net terms and the due date should be set automatically. Vaue should be in the format yyyy-MM-dd HH:mm:ss. Time is optional.
netterm.term Invoice terms
netterm.detail Invoice terms detail
netterm.xy_days Invoice Net XY terms days
netterm.xy_discount_days Invoice Net XY terms discount days
netterm.xy_discount_amount Invoice Net XY terms discount amount in base currency without currency symbol
netterm.xy_discount_calculation_total Invoice Net XY terms discount calculation total. Can be default, subtotal, grand_total
netterm.xy_late_fee Invoice Net XY terms late fee amount in base currency without currency symbol
netterm.xy_late_fee_calculation_total Invoice Net XY terms late fee calculation total. Can be default, subtotal, grand_total
send_email Accepts a value of 0 or 1. Will send email for new invoice if set to 1. Defaults to 1.
comment Object used for comment config. Setting this value will prevent the comment from immediately adding to the Order Status History and instead will be added as a comment on the invoice itself. CommentConfig

ExtraDataTotal

Param Notes
code Total being updated. (shipping, discount, payment_surcharge, tax)
base_raw_value Value to set the total to. (number)

CommentConfig

Param Notes
is_visible_on_front Accepts a value of 0 of 1. If set to 1 the comment will be visible to the customer in both the email and the My Account section.

Example request body:

{
    "orderIncrementId": "100002958",
    "itemsQty": {
        "60012": "1"
    },
    "comment": "This is a comment that will show up in the order history",
    "shipmentData": {
        "send_email": "1",
        "ship_immediately": true,
        "tracking": [
            {
                "carrier_code": "usps",
                "number": "987234987235",
                "title": "United States Postal Service"
            }
        ],
        "attachments": [
            {
                "file_name": "attachment_2.png",
                "file_mime_type": "image/png",
                "file_content": "iVBORw0KGgo..."
            }
        ]
    },
    "extraData": {
        "send_email": "1",
        "ignore_qty_multiplier": true,
        "totals_info": [
            {
                "code": "shipping",
                "base_raw_value": "101"
            },
            {
                "code": "discount",
                "base_raw_value": "102"
            },
            {
                "code": "payment_surcharge",
                "base_raw_value": "103"
            },
            {
                "code": "tax",
                "base_raw_value": "104"
            }
        ],
        "due_date": "2024-01-20 10:20:30",
        "netterm": {
            "term": "net10"
        },
        "comment": {
            "is_visible_on_front": "1"
        },
        "attachments": [
            {
                "file_name": "attachment_2.png",
                "file_mime_type": "image/png",
                "file_content": "iVBORw0KGgo..."
            }
        ]
    }
}

Example response (Send), HTTP 200:

"7"

Pay

POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill/pay

Param Notes
bill_id The internal ID of the bill being paid.
data The BillConfigData object.

BillConfigData

Param Notes
saved_payment An id from List Saved Payments, e.g. cim:11 or cryozonic_achpayments:pm_bank_1. It must belong to the invoice's account.
send_email Flag used to trigger email send. Value can be 1 or 0.
shipmentData (Boolean or ShipmentData) If set to true then the shipment will be created at the time of the request. If set to false it will configure the shipment to be created when the bill is paid and the invoice is created. (Default: false). Can use ShipmentData object to configure specifically. Ignored when amount is provided.
comment_customer_notify Should the comment text be added to the email. Value should be 1 or 0. Ignored when amount is provided (use comments instead).
comment_text The comment to be added to the invoice. Value should be a string. Ignored when amount is provided (use comments instead).
is_visible_on_front Can the comment be visible on the storefront by the customer. Value can be 1 or 0. Ignored when amount is provided (use comments instead).
capture_case "online" to capture an authorization or "offline" to make an offline payment. Must be "offline" (or omitted) when amount is provided.
amount (Optional) Amount to pay toward the bill, in the store's base currency. Must be greater than 0 and no more than the bill's remaining balance. When provided, a partial payment is recorded against the bill instead of paying it in full. The invoice is created automatically once the remaining balance reaches 0. Only offline payments are supported.
is_percentage (Optional) If set to 1, amount is treated as a percentage (0–100) of the bill's remaining balance. Value can be 1 or 0. (Default: 0)
method_code (Optional) Offline payment method code to record on the payment (ex. checkmo, purchaseorder, banktransfer, cashondelivery). Only used when amount is provided.
method_code_comment (Optional) Note to go with method_code, such as a check or reference number. Value should be a string. Only used when amount is provided.
comments (Optional) Array of comment strings or PaymentCommentData objects to add to the payment. Only used when amount is provided.
created_at (Optional) Date/time to record as the payment date (ex. 2026-09-24 14:30:00). Defaults to the current time. Only used when amount is provided.

Response

PaymentCommentData

Param Notes
text The comment text. Value should be a string.
is_customer_notified Should the comment be included in the payment email to the customer. Value can be 1 or 0.
is_visible_on_front Can the comment be visible on the storefront by the customer. Value can be 1 or 0.

ShipmentData

Param Notes
do_shipment Should ship at the time the invoice is created. Value can be 1 or 0.
ship_items Object key is itemId and the value is qty. (ex. { "311": "2", "312": "1" } Would ship 2 of order item 311 and 1 of order item 312) The Order Item ID that is used will always be the Parent ID in the event of a Configurable/Grouped/Bundled product. (Optional, will use all items/quantities that are being invoiced if not provided.)
tracking Array of TrackingData

TrackingData

Param Notes
carrier_code Code for the shipment carrier used for tracking. A list is available using the Get Carriers method.
number Tracking Number
title Tracking Carrier title

Example request body:

{
    "bill_id": "8377",
    "data": {
        "capture_case": "online",
        "send_email": "1",
        "shipmentData": {
            "ship_items": {
                "311": "1"
            },
            "tracking": [
                {
                    "carrier_code": "usps",
                    "number": "987234987235",
                    "title": "United States Postal Service"
                }
            ]
        },
        "comment_customer_notify": "1",
        "comment_text": "This comment will be saved when paying the bill.",
        "is_visible_on_front": "1"
    }
}

Example response (Send), HTTP 200:

"100000259"

Get

GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill?id=482

Query parameters:

NameExampleNotes
id482ID of bill. (Optional if order_id is used)
order_id796If used will get latest unpaid bill by order_id. (Optional if id is used)

Example response (Get), HTTP 200:

{
    "order_id": "678",
    "store_id": "1",
    "customer_id": "48",
    "billing_address_id": "1351",
    "shipping_address_id": "1352",
    "global_currency_code": "USD",
    "base_currency_code": "USD",
    "store_currency_code": "USD",
    "order_currency_code": "USD",
    "store_to_base_rate": "1.0000",
    "store_to_order_rate": "1.0000",
    "base_to_global_rate": "1.0000",
    "base_to_order_rate": "1.0000",
    "discount_description": null,
    "avatax_landed_cost_import_duties_amount": null,
    "base_avatax_landed_cost_import_duties_amount": null,
    "avatax_fixed_tax_amount": null,
    "base_avatax_fixed_tax_amount": null,
    "avatax_collected_taxes": null,
    "total_qty": 4,
    "bill": {
        "id": "482",
        "order_id": "678",
        "invoice_id": null,
        "increment_id": "100000434",
        "replaced_increment_id": null,
        "key": "665f7c62ab492211884440",
        "state": "open",
        "status": "open",
        "can_edit": "0",
        "is_paid": "0",
        "payment_method": null,
        "is_custom_payment_method": "0",
        "allowed_payment_methods": null,
        "is_void": "0",
        "base_total": "220.0000",
        "total": "220.0000",
        "due_date": "2024-06-05 03:59:59",
        "is_custom_due_date": "0",
        "is_due_on_receipt": "1",
        "config": {
            "items": {
                "54557": "1",
                "54558": "1",
                "54559": "1",
                "54560": "1"
            },
            "create_invoice": "1",
            "do_shipment": "0",
            "send_email": "1",
            "void_unpaid_bills": "0",
            "comment_text": "",
            "totals_info": [
                {
                    "code": "subtotal",
                    "label": "Subtotal",
                    "raw_value": "4.00",
                    "base_raw_value": "4.00",
                    "value": "$4.0000",
                    "class": "total-md",
                    "include": "true",
                    "base_value": "",
                    "orig_base_raw_value": "4.00"
                },
                {
                    "code": "shipping",
                    "label": "Shipping",
                    "raw_value": "216.00",
                    "base_raw_value": "216.00",
                    "value": "$216.0000",
                    "class": "total-md",
                    "include": "true",
                    "base_value": "",
                    "orig_value": "",
   
... (truncated)

Get All

GET https://container-url.zoeysite.com/api/rest/sales2/orders/bills?order[order_id]=DESC&filters[created_at][from]=2024-01-01&filters[created_at][to]=2024-12-31

Query parameters:

NameExampleNotes
limit2If used will get latest unpaid bill by order_id. (Optional if id is used)
page1
order[order_id]DESC
filters[order_id]41
filters[total_qty][gt]1
filters[created_at][from]2024-01-01
filters[created_at][to]2024-12-31

Example response (Get), HTTP 200:

{
    "order_id": "678",
    "store_id": "1",
    "customer_id": "48",
    "billing_address_id": "1351",
    "shipping_address_id": "1352",
    "global_currency_code": "USD",
    "base_currency_code": "USD",
    "store_currency_code": "USD",
    "order_currency_code": "USD",
    "store_to_base_rate": "1.0000",
    "store_to_order_rate": "1.0000",
    "base_to_global_rate": "1.0000",
    "base_to_order_rate": "1.0000",
    "discount_description": null,
    "avatax_landed_cost_import_duties_amount": null,
    "base_avatax_landed_cost_import_duties_amount": null,
    "avatax_fixed_tax_amount": null,
    "base_avatax_fixed_tax_amount": null,
    "avatax_collected_taxes": null,
    "total_qty": 4,
    "bill": {
        "id": "482",
        "order_id": "678",
        "invoice_id": null,
        "increment_id": "100000434",
        "replaced_increment_id": null,
        "key": "665f7c62ab492211884440",
        "state": "open",
        "status": "open",
        "can_edit": "0",
        "is_paid": "0",
        "payment_method": null,
        "is_custom_payment_method": "0",
        "allowed_payment_methods": null,
        "is_void": "0",
        "base_total": "220.0000",
        "total": "220.0000",
        "due_date": "2024-06-05 03:59:59",
        "is_custom_due_date": "0",
        "is_due_on_receipt": "1",
        "config": {
            "items": {
                "54557": "1",
                "54558": "1",
                "54559": "1",
                "54560": "1"
            },
            "create_invoice": "1",
            "do_shipment": "0",
            "send_email": "1",
            "void_unpaid_bills": "0",
            "comment_text": "",
            "totals_info": [
                {
                    "code": "subtotal",
                    "label": "Subtotal",
                    "raw_value": "4.00",
                    "base_raw_value": "4.00",
                    "value": "$4.0000",
                    "class": "total-md",
                    "include": "true",
                    "base_value": "",
                    "orig_base_raw_value": "4.00"
                },
                {
                    "code": "shipping",
                    "label": "Shipping",
                    "raw_value": "216.00",
                    "base_raw_value": "216.00",
                    "value": "$216.0000",
                    "class": "total-md",
                    "include": "true",
                    "base_value": "",
                    "orig_value": "",
   
... (truncated)

Void

DELETE https://container-url.zoeysite.com/api/rest/sales2/orders/bill?id=8&order_id=26

Query parameters:

NameExampleNotes
id8ID of bill. (Optional if order_id is used)
order_id26If used will get latest unpaid bill by order_id. (Optional if id is used)

Email

GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill/email?id=8

Query parameters:

NameExampleNotes
id8Id of bill

Print

GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill/print?id=8

Response

Key Type Description
file string A base64 encoded PDF.
filename string PDF file name.

Query parameters:

NameExampleNotes
id8Id of Bill

Update

POST https://container-url.zoeysite.com/api/rest/sales2/orders/bill/update

Param Notes
bill_id Invoice ID
data.items This is used to overwrite the invoice items quantity and price. Uses ItemsData.
data.totals_info This is used to set custom totals for invoice. Array of TotalData.
data.due_date This is used to set the due date on the invoice. Set this value to null, if setting net terms and the due date should be set automatically. Vaue should be in the format yyyy-MM-dd HH:mm:ss. Time is optional.
data.netterm This is used to set netterm data on the invoice. Uses NetTermData
data.external_invoice_id This is used to set the external invoice id on the invoice.

ItemsData

Param Notes
objectKey Object key is order_item_id from the invoice.
qty The quantity of the invoice item to be set. This overrides the current qty of the invoice item.
base_price The base price of the invoice item to be set in base currency without currency symbol. This overwrites the current base_price of the invoice item.

TotalData

Param Notes
code Total being updated. (shipping, discount, payment_surcharge, tax).
base_raw_value Value to set the total to. (number).

NetTermData

Param Notes
term Invoice terms. Set to null to remove terms
detail Invoice terms detail
xy_days Invoice Net XY terms days
xy_discount_days Invoice Net XY terms discount days
xy_discount_amount Invoice Net XY terms discount amount in base currency without currency symbol
xy_discount_calculation_total Invoice Net XY terms discount calculation total. Can be default, subtotal, grand_total
xy_late_fee Invoice Net XY terms late fee amount in base currency without currency symbol
xy_late_fee_calculation_total Invoice Net XY terms late fee calculation total. Can be default, subtotal, grand_total

Example request body:

{
    "bill_id": "5664",
    "data": {
        "items": {
            "8952": {
                "qty": "2",
                "base_price": "25.99"
            },
            "8953": {
                "qty": "3",
                "base_price": "19.99"
            }
        },
        "totals_info": [
            {
                "code": "shipping",
                "base_raw_value": "101"
            },
            {
                "code": "discount",
                "base_raw_value": "102"
            },
            {
                "code": "payment_surcharge",
                "base_raw_value": "103"
            },
            {
                "code": "tax",
                "base_raw_value": "104"
            }
        ],
        "due_date": "2024-01-20 10:20:30",
        "netterm": {
            "term": "net10"
        },
        "external_invoice_id": "EXT_INV_01"
    }
}

Saved Payments

GET https://container-url.zoeysite.com/api/rest/sales2/orders/bill/savedPayments?id={{bill_id}}

GET /sales2/orders/bill/savedPayments?id={{billId}}

Returns the saved cards and verified ACH bank accounts that can be used to pay an invoice. These belong to the account (company) that the invoice's order is on. Pass an id from this list as saved_payment to Pay Invoice (POST /sales2/orders/bill/pay) to charge it.

Invoicing must be enabled on the store, and the invoice's order must be on an account.

Query Parameters

Parameter Type Required Description
id integer Yes The invoice (bill) ID. This is the same ID used by /sales2/orders/bill/print.

Permissions

The API user's role needs the List Saved Payments For Invoice resource (sales/order/invoice/getBillSavedPayments).

Response

200 OK: an array of saved payments. The array is empty if the account has no saved payments that can be charged.

Field Type Description
id string Reference to pass as saved_payment to Pay Invoice. Format: :.
type string card or ach.
method string Payment method the payment is saved under: cim, authorizenet, cryozonic_stripe, gene_braintree_creditcard, cryozonic_achpayments, or cryozonic_achpayments_ach.
label string Display label. Uses the nickname if one is set, otherwise e.g. Visa ending in 4242.
brand string null
last4 string null
exp_month string null
exp_year string null

Only payment methods that AutoPay supports are listed (Authorize.Net CIM, Stripe, Braintree, Stripe ACH). ACH accounts that haven't been verified yet are left out.

Example Response

[
  {
    "id": "cim:11",
    "type": "card",
    "method": "cim",
    "label": "Visa ending in 1111",
    "brand": "Visa",
    "last4": "1111",
    "exp_month": "04",
    "exp_year": "2029"
  },
  {
    "id": "cryozonic_stripe:card_abc",
    "type": "card",
    "method": "cryozonic_stripe",
    "label": "Office card",
    "brand": "MasterCard",
    "last4": "4444",
    "exp_month": null,
    "exp_year": null
  },
  {
    "id": "cryozonic_achpayments:pm_bank_1",
    "type": "ach",
    "method": "cryozonic_achpayments",
    "label": "Chase ending in 6789",
    "brand": "Chase",
    "last4": "6789",
    "exp_month": null,
    "exp_year": null
  }
]

Errors

All errors return 400 Bad Request with a message.

Cause Message
Invoicing is not enabled on the store Invoicing is not enabled.
id is missing or not numeric id must be an invoice ID.
No invoice with that ID Invoice with ID {id} not found.
The invoice's order is not on an account This invoice is not on an account. Saved payments can only be used for invoices on an account.

Query parameters:

NameExampleNotes
id{{bill_id}}The invoice (bill) ID. This is the same ID used by /sales2/orders/bill/print.