Zoey REST API reference ยท Interactive version: apidocs.zoey.com

Orders

Orders: Invoices (Internal Payments)

The Invoice endpoint is available for Adding Comments to an Invoice, Creating a Payment for an Invoice, Getting Payment Data, or Printing / Emailing the Payment PDF.

Comments

Add

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

Param Type Notes Required
invoiceIncrementId string The increment id of the Invoice. Yes
comment string The comment being added to the invoice. Yes
email boolean Notify the customer of the comment being added. No (default: false)
includeInEmail boolean Include the comment in the notification email. No (default: false)

Example request body:

{
    "invoiceIncrementId": "100000030",
    "comment": "This is my test comment.",
    "email": true,
    "includeInEmail": true
}

Create

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

This endpoint creates a Payment.
It can also create a Shipment for certain items.

Param Notes
orderIncrementId The increment ID of the order to create the invoice for.
itemsQty Object key is itemId and the value is qty. (ex. { "311": "2", "312": "1" } Would invoice 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. If an empty JSON object is posted then it will process ALL remaining items.
comment Message to send to create on invoice for customer to see. (Optional)
email Flag to send invoice email to customer on creation. Use value 1 to send
includeComment Flag to include comment on the email, if sent. Use value 1 to include.
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.)
tracking Array of TrackingData
send_email 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

ExtraDataTotal

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

Example request body:

{
    "orderIncrementId": "100008707",
    "itemsQty": {
        "71446": 256,
        "71447": 1,
        "71449": 1,
        "71451": 1
    },
    "comment": "Created By API",
    "email": "0",
    "includeComment": "0",
    "shipmentData": {
        "send_email": "1",
        "ship_items": {
            "71447": 1
        },
        "tracking": [
            {
                "carrier_code": "usps",
                "number": "987234987235",
                "title": "United States Postal Service"
            }
        ],
        "attachments": [
            {
                "file_name": "attachment_5.jpg",
                "file_mime_type": "image/png",
                "file_content": "iVBORw0..."
            }
        ]
    },
    "extraData": {
        "totals_info": [
            {
                "code": "shipping",
                "base_raw_value": "0"
            },
            {
                "code": "discount",
                "base_raw_value": "20"
            },
            {
                "code": "payment_surcharge",
                "base_raw_value": "0"
            },
            {
                "code": "tax",
                "base_raw_value": "0"
            }
        ]
    }
}

Example response (Create), HTTP 200:

"100000066"

Get

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

Query parameters:

NameExampleNotes
id100000455Increment ID of Invoice

Example response (Get), HTTP 200:

{
    "store_id": "1",
    "base_grand_total": "117.7000",
    "shipping_tax_amount": "0.0000",
    "tax_amount": "5.7000",
    "base_tax_amount": "5.7000",
    "store_to_order_rate": "1.0000",
    "base_shipping_tax_amount": "0.0000",
    "base_discount_amount": "0.0000",
    "base_to_order_rate": "1.0000",
    "grand_total": "117.7000",
    "shipping_amount": "45.0000",
    "subtotal_incl_tax": "72.7000",
    "base_subtotal_incl_tax": "72.7000",
    "store_to_base_rate": "1.0000",
    "base_shipping_amount": "45.0000",
    "total_qty": "10.0000",
    "base_to_global_rate": "1.0000",
    "subtotal": "67.0000",
    "base_subtotal": "67.0000",
    "discount_amount": "0.0000",
    "billing_address_id": "1587",
    "is_used_for_refund": null,
    "order_id": "796",
    "email_sent": "1",
    "can_void_flag": null,
    "state": "3",
    "shipping_address_id": "1588",
    "store_currency_code": "USD",
    "transaction_id": null,
    "order_currency_code": "USD",
    "base_currency_code": "USD",
    "global_currency_code": "USD",
    "increment_id": "100000455",
    "replaced_increment_id": null,
    "created_at": "2024-05-23 21:29:34",
    "internal_created_at": "2024-05-23 21:29:34",
    "updated_at": "2024-05-23 21:30:25",
    "hidden_tax_amount": "0.0000",
    "base_hidden_tax_amount": "0.0000",
    "shipping_hidden_tax_amount": "0.0000",
    "base_shipping_hidden_tax_amnt": null,
    "shipping_incl_tax": "45.0000",
    "base_shipping_incl_tax": "45.0000",
    "base_total_refunded": null,
    "discount_description": null,
    "old_invoice_id": null,
    "old_invoice_increment_id": null,
    "base_giftcard_discount": "0.0000",
    "giftcard_discount": "0.0000",
    "payment_fee_amount": null,
    "base_payment_fee_amount": null,
    "payment_installment_fee_amount": null,
    "base_payment_installment_fee_amount": null,
    "zoey_custom_options_price": null,
    "base_zoey_custom_options_price": null,
    "is_archived": "0",
    "apply_store_credit": "0",
    "store_credit_amount": "0.0000",
    "base_store_credit_amount": "0.0000",
    "payment_surcharge_amount": "0.0000",
    "base_payment_surcharge_amount": "0.0000",
    "net_term_discount": "0.0000",
    "base_net_term_discount": "0.0000",
    "net_term_late_fee": "0.0000",
    "base_net_term_late_fee": "0.0000",
    "avatax_landed_cost_import_duties_amount": null,
    "base_avatax_landed_cost_import_duties_amount": null,
    "avatax_collected_taxes": null,
    "avatax_fixed_tax_amount": null,
    "base_a
... (truncated)

Get All

GET https://container-url.zoeysite.com/api/rest/sales2/orders/invoices?filters[include_comments]=1

Query parameters:

NameExampleNotes
limit2Limit the amount of results returned. (Optional)
page1Paginate the limit. (Optional)
order[created_at]ASCUsed to sort by property key / direction. (Optional)
filters[increment_Id][gt]100000001Used to filter results by property. (Optional)
filters[total_qty][gt]1Qty Filtering Example
filters[include_comments]1Include comments in the response. (Boolean Flag 1 or 0. Optional)
filters[include_order_increment_id]1Include order's increment_id in the response (Boolean Flag 1 or 0. Optional)

Print

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

Response

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

Query parameters:

NameExampleNotes
id100000015Increment ID of invoice

Email

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

Query parameters:

NameExampleNotes
id100000015Increment ID of invoice.