Spec - Invoices

Table Of Contents

• Get Invoices
• Add Invoices
• Edit Invoices
• Delete Invoices

Get Invoices

This function allows the caller to retrieve Invoices from the database. Search parameters should be specified inside the tag. Invoices can be retrieved by invoice ID, contact (ID or name), or group (ID or Name). Leaving all search criteria blank would return all of the invoices in the account.

Input

• invoice_id
• contact_id
• contact_firstname
• contact_lastname
• group_id (return all invoices sent to group)
• group_name
• opened_date (YYYYMMDDHHmm format)
• external_id

If no search criteria, return all invoices in the account.

Output

Success or failure. For each Invoice found:

• Invoice_id
• Contact_id
• Contact_firstname
• Contact_lastname
• Contact_email
• Contact_company
• Contact_address1
• Contact_address2
• Contact_city
• Contact_state
• Contact_zip
• Contact_country
• Contact_phone
• Contact_mobile
• Contact_fax
• Group_id
• Group_name
• CreatedDatetime
• Sent_date
• Opened_date
• Due_date
• Description
• InvoiceFooter
• Paid_date
• TransactionID (the transaction ID of the invoice payment)
• Payment_amount
• QuoteOrInvoice
• ExternalID
• SalesRepContactID
• SalesRepFirstname
• SalesRepLastname
• SalesRepEmail
• ShipmentDate
• ShipmentAdvancedDaysWorkflow
• ShipmentWorkflowID
• ShippingMethod
• ShipToName
• ShipToAddress
• ShipToCity
• ShipToState
• ShipToZip
• ShipToCountry
• ShipToPhone
• InvoiceType
• InvoiceStatus
• InvoiceTotal
• InvoiceLineItems
  • Lineitem_id
  • Description
  • Unit_cost
  • Quantity
  • SKU
  • Event_id
  • Total_unit_cost

Example Request

<GetInvoicesRequest></GetInvoicesRequest>

Example Request

<GetInvoicesRequest contact_firstname="Jeff" contact_lastname="Gordon"></GetInvoicesRequest>

Example Request

<GetInvoicesRequest invoice_id="73"></GetInvoicesRequest>

Example Request

<GetInvoicesRequest opened_date="201312040000"></GetInvoicesRequest>

Example Request

<GetInvoicesRequest sent_date="20120201"></GetInvoicesRequest>

Example Request (filter by ExternalID)

<GetInvoicesRequest external_id="47217"></GetInvoicesRequest>

Successful Response

<GetInvoicesResponse>
      <Result>Success</Result>
      <Invoices>
           <Invoice>
                <Invoice_id>83</Activity_id>
                <Contact_id>443</Contact_id>
                <Contact_firstname>Jeff</Contact_firstname>
                <Contact_lastname>Gordon</Contact_lastname>
                <Contact_email>jeff@gordon.com</Contact_email>
                <Contact_company>Gordon Tech</Contact_company>
                <Contact_address1>1 Gordon Road</Contact_address1>
                <Contact_address2>Gordon Street</Contact_address2>
                <Contact_city>East Gordon</Contact_city>
                <Contact_state>CA</Contact_state>
                <Contact_zip>12345</Contact_zip>
                <Contact_country>USA</Contact_country>
                <Contact_phone>+101115035435</Contact_phone>
                <Contact_mobile>+101115035436</Contact_mobile>
                <Contact_fax>+101115035437</Contact_fax>
                <Group_id>8</Group_id>
                <Group_name>Test Team</Group_name>
                <CreatedDatetime>2023-06-12 10:00:48</CreatedDatetime>
                <Sent_date>201204120855</Sent_date>
                <Opened_date>201203120915</Opened_date>
                <Due_date>20120412</Due_date>
                <Description>Invoice for Parts Delivered January, 2012</Description>
                <InvoiceFooter><![CDATA[<p>The <strong>quick </strong><em>brown </em><u>fox </u>jumps over the lazy dog.</p>
                    <p>The <strong>quick </strong><em>brown </em><u>fox </u>jumps over the lazy dog.</p>
                ]]></InvoiceFooter>
                <Paid_date>201204120855</Paid_date>
                <TransactionID>1234554321</TransactionID>
                <Payment_amount>61.93</Payment_amount>
                <QuoteOrInvoice>Invoice</QuoteOrInvoice>
                <ExternalID>1234</ExternalID>
                <SalesRepContactID>123</SalesRepContactID>
                <SalesRepFirstname>Bob</SalesRepFirstname>
                <SalesRepLastname>Bobbington</SalesRepLastname>
                <SalesRepEmail>bob@bobbington.com</SalesRepEmail>
                <ShipmentDate>2012-04-01</ShipmentDate>
                <ShipmentAdvancedDaysWorkflow>2</ShipmentAdvancedDaysWorkflow>
                <ShipmentWorkflowID>22</ShipmentWorkflowID>
                <ShippingMethod>USPS</ShippingMethod>
                <ShipToName>Jeff Gordon</ShipToName>
                <ShipToAddress>1 Gordon Road, Gordon Street</ShipToAddress>
                <ShipToCity>Easy Gordon</ShipToCity>
                <ShipToState>CA</ShipToState>
                <ShipToZip>12345</ShipToZip>
                <ShipToCountry>United States</ShipToCountry>
                <ShipToPhone>+12015550123</ShipToPhone>
                <InvoiceType>30 Day</InvoiceType>
                <InvoiceStatus>PAID</InvoiceStatus>
                <InvoiceTotal>62.00</InvoiceTotal>
                <InvoiceLineItems>
                     <InvoiceLineItem>
                          <Lineitem_id>23</Lineitem_id>
                          <Event_id>12</Event_id>
                          <Quantity>2</Quantity>
                          <Description>Test Widget</Description>
                          <Sku>11111</Sku>
                          <Unit_cost>6.00</Unit_cost>
                          <Total_unit_cost>12.00</Total_unit_cost>
                     </InvoiceLineItem>
                     <InvoiceLineItem>
                          <Lineitem_id>24</Lineitem_id>
                          <Event_id></Event_id>
                          <Quantity>5</Quantity>
                          <Description>Another Test Widget</Description>
                          <Sku>22222</Sku>
                          <Unit_cost>10.00</Unit_cost>
                          <Total_unit_cost>50.00</Total_unit_cost>
                     </InvoiceLineItem>
                </InvoiceLineItems>
           </Invoice>
           <Invoice>
                <Invoice_id>84</Activity_id>
                <Contact_id>444</Contact_id>
                <Contact_firstname>Steve</Contact_firstname>
                <Contact_lastname>Watson</Contact_lastname>
                <Contact_email>steve@watson.com</Contact_email>
                <Contact_company>Watson Tech</Contact_company>
                <Contact_address1>1 Watson Road</Contact_address1>
                <Contact_address2>Watson Street</Contact_address2>
                <Contact_city>East Watson</Contact_city>
                <Contact_state>CA</Contact_state>
                <Contact_zip>12345</Contact_zip>
                <Contact_country>USA</Contact_country>
                <Contact_phone>+102115035435</Contact_phone>
                <Contact_mobile>+102115035436</Contact_mobile>
                <Contact_fax>+102115035437</Contact_fax>
                <Group_id>12</Group_id>
                <Group_name>Test Team 2</Group_name>
                <CreatedDatetime>2023-06-12 10:00:48</CreatedDatetime>
                <Sent_date>201206111301</Sent_date>
                <Opened_date>201206111331</Opened_date>
                <Due_date>20120711</Due_date>
                <Description>Invoice for Services</Description>
                <InvoiceFooter></InvoiceFooter>
                <Paid_date>201207131354/Paid_date>
                <TransactionID>1234554321</TransactionID>
                <Payment_amount>70.00</Payment_amount>
                <QuoteOrInvoice>Quote</QuoteOrInvoice>
                <ExternalID></ExternalID>
                <SalesRepContactID>123</SalesRepContactID>
                <SalesRepFirstname>Bob</SalesRepFirstname>
                <SalesRepLastname>Bobbington</SalesRepLastname>
                <SalesRepEmail>bob@bobbington.com</SalesRepEmail>
                <ShipmentDate>2012-07-01</ShipmentDate>
                <ShipmentAdvancedDaysWorkflow>2</ShipmentAdvancedDaysWorkflow>
                <ShipmentWorkflowID>22</ShipmentWorkflowID>
                <ShippingMethod>USPS</ShippingMethod>
                <ShipToName>Test Ship</ShipToName>
                <ShipToAddress>Address 1, Street 2</ShipToAddress>
                <ShipToCity>City</ShipToCity>
                <ShipToState>State</ShipToState>
                <ShipToZip>01011</ShipToZip>
                <ShipToCountry>United States</ShipToCountry>
                <ShipToPhone>+12015550123</ShipToPhone>
                <InvoiceType>30 Day</InvoiceType>
                <InvoiceStatus>PAID</InvoiceStatus>
                <InvoiceTotal>70.00</InvoiceTotal>
                <InvoiceLineItems>
                     <InvoiceLineItem>
                          <Lineitem_id>45</Lineitem_id>
                          <Event_id></Event_id>
                          <Quantity>1</Quantity>
                          <Description>Test Service</Description>
                          <Sku>33333</Sku>
                          <Unit_cost>45.00</Unit_cost>
                          <Total_unit_cost>45.00</Total_unit_cost>
                     </InvoiceLineItem>
                     <InvoiceLineItem>
                          <Lineitem_id>48</Lineitem_id>
                          <Event_id></Event_id>
                          <Quantity>1</Quantity>
                          <Description>Test Service 2</Description>
                          <Sku>44444</Sku>
                          <Unit_cost>25.00</Unit_cost>
                          <Total_unit_cost>25.00</Total_unit_cost>
                     </InvoiceLineItem>
                </InvoiceLineItems>
           </Invoice>
      </Invoices>
 </GetInvoicesResponse>

Add Invoices

This function allows the caller to add one or more invoices.

To mark an invoice as paid, pass the Paid_date, TransactionID and Payment_amount arguments.

To make the invoice be sent after being created, pass the SendInvoice argument. The SendInvoiceCCEmails argument can be used to include CC recipients when sending the invoice.

Input

• request_id (optional)
• Contact_id (required)
• Group_id (required)
• QuoteOrInvoice (required, 'Quote', 'Invoice', 'Purchase Order')
• Sent_date (optional, YYYYMMDDHHmm format)
• Due_date (optional, YYYYMMDD format)
• Description (required)
• InvoiceFooter (optional)
• Paid_date (optional, YYYYMMDDHHmm format)
• TransactionID (optional, the transaction ID, for example the PayPal ID, of the invoice payment. Max length is 32 characters)
• Payment_amount (optional)
• ExternalID (optional)
• SalesRepContactID (optional)
• ShipmentDate (optional)
• ShipmentAdvancedDaysWorkflow (optional)
• ShipmentWorkflowID (optional)
• ShippingMethod (optional)
• ShipToName (optional)
• ShipToAddress (optional)
• ShipToCity (optional)
• ShipToState (optional)
• ShipToZip (optional)
• ShipToCountry (optional)
• ShipToPhone (optional)
• InvoiceType (optional)
• InvoiceStatus (optional)
• SendInvoice (optional, true/false)
• SendInvoiceCCEmails (optional, separated by comma)
• InvoiceLineItems
  • Description (required)
  • Unit_cost (required)
  • Quantity (required)
  • Sku (optional)
  • Event_id (optional)

Output

For each Invoice ID, success or failure.

Example Request

<AddInvoicesRequest>
      <Invoices>
           <Invoice request_id="a1b2c3">
                <Contact_id>788</Contact_id>
                <Group_id>8</Group_id>
                <QuoteOrInvoice>Invoice</QuoteOrInvoice>
                <ExternalID>1234</ExternalID>
                <Sent_date>201202210855</Sent_date>
                <Due_date>20120321</Due_date>
                <Description>Sample Invoice 1</Description>
                <InvoiceFooter><![CDATA[<p>The <strong>quick </strong><em>brown </em><u>fox </u>jumps over the lazy dog.</p>
                <p>The <strong>quick </strong><em>brown </em><u>fox </u>jumps over the lazy dog.</p>]]></InvoiceFooter>
                <Paid_date>201203121423</Paid_date>
                <TransactionID>1234554321</TransactionID>
                <Payment_amount>50.00</Payment_amount>
                <SalesRepContactID>123</SalesRepContactID>
                <ShipmentDate>2012-03-01</ShipmentDate>
                <ShipmentAdvancedDaysWorkflow>2</ShipmentAdvancedDaysWorkflow>
                <ShipmentWorkflowID>1</ShipmentWorkflowID>
                <ShippingMethod>USPS</ShippingMethod>
                <ShipToName>Jeff Gordon</ShipToName>
                <ShipToAddress>1 Gordon Road, Gordon Street</ShipToAddress>
                <ShipToCity>Easy Gordon</ShipToCity>
                <ShipToState>CA</ShipToState>
                <ShipToZip>12345</ShipToZip>
                <ShipToCountry>United States</ShipToCountry>
                <ShipToPhone>+12015550123</ShipToPhone>
                <InvoiceType>30 Day</InvoiceType>
                <InvoiceStatus>PAID</InvoiceStatus>
                <SendInvoice>true</SendInvoice>
                <SendInvoiceCCEmails>ccrecipient1@gmail.com, ccrecipient2@gmail.com</SendInvoiceCCEmails>
                <InvoiceLineItems>
                     <InvoiceLineItem>
                          <Event_id>21</Event_id>
                          <Quantity>1</Quantity>
                          <Description>My Test Widget</Description>
                          <Sku>55555</Sku>
                          <Unit_cost>15.00</Unit_cost>
                     </InvoiceLineItem>
                     <InvoiceLineItem>
                          <Quantity>7</Quantity>
                          <Description>My Other Test Widget</Description>
                          <Sku>66666</Sku>
                          <Unit_cost>5.00</Unit_cost>
                     </InvoiceLineItem>
                </InvoiceLineItems>
           </Invoice>
           <Invoice request_id="d4e5f6">
                <Contact_id>791</Contact_id>
                <Group_id>9</Group_id>
                <QuoteOrInvoice>Quote</QuoteOrInvoice>
                <Due_date>20120323</Due_date>
                <Description>Sample Invoice 2</Description>
                <InvoiceFooter>The quick brown fox jumps over the lazy dog.</InvoiceFooter>
                <SalesRepContactID>123</SalesRepContactID>
                <ShipmentDate>2012-03-01</ShipmentDate>
                <ShipmentAdvancedDaysWorkflow>2</ShipmentAdvancedDaysWorkflow>
                <ShipmentWorkflowID>1</ShipmentWorkflowID>
                <ShippingMethod>USPS</ShippingMethod>
                <InvoiceType>30 Day</InvoiceType>
                <InvoiceStatus>UNPAID</InvoiceStatus>
                <InvoiceLineItems>
                     <InvoiceLineItem>
                          <Quantity>1</Quantity>
                          <Description>My Test Service</Description>
                          <Sku>77777</Sku>
                          <Unit_cost>60.00</Unit_cost>
                     </InvoiceLineItem>
                     <InvoiceLineItem>
                          <Quantity>1</Quantity>
                          <Description>My Other Test Service</Description>
                          <Sku>88888</Sku>
                          <Unit_cost>75.00</Unit_cost>
                     </InvoiceLineItem>
                </InvoiceLineItems>
           </Invoice>
      </Invoices>
 </AddInvoicesRequest>

Successful Response

<AddInvoicesResponse>
      <Invoices>
           <Invoice request_id="a1b2c3">
                <Invoice_id>741</Invoice_id>
                <Result>Success</Result>
           </Invoice>
           <Invoice request_id="d4e5f6">
                <Invoice_id>742</Invoice_id>
                <Result>Success</Result>
           </Invoice>
      </Invoices>
 </AddInvoicesResponse>

Edit Invoices

This function allows the caller to update one or more invoices. To mark an invoice as paid, pass the Paid_date, TransactionID and Payment_amount arguments.

Input

• invoice_id (required)
• request_id (optional)
• QuoteOrInvoice (optional, 'Quote', 'Invoice', 'Purchase Order')
• ExternalID (optional)
• SalesRepContactID (optional)
• Group_id (optional)
• Due_date (optional, YYYYMMDD format)
• InvoiceType (optional)
• InvoiceStatus (optional)
• ShipmentAdvancedDaysWorkflow (optional)
• ShipmentWorkflowID (optional)
• ShipmentDate (optional, YYYY-MM-DD format)
• ShipToName (optional)
• ShipToAddress (optional)
• ShipToCity (optional)
• ShipToState (optional)
• ShipToZip (optional)
• ShipToCountry (optional)
• ShipToPhone (optional)
• ShippingMethod (optional)
• Description (optional)
• InvoiceFooter (optional)
• Paid_date (optional, YYYYMMDDHHmm format)
• TransactionID (optional, the transaction ID, for example the PayPal ID, of the invoice payment. Max length is 32 characters)
• Payment_amount (optional)
• AddInvoiceLineItems (optional)
  • Quantity (required)
  • Sku (optional)
  • Description (required)
  • Unit_cost (required)
  • Event_id (optional)
• EditInvoiceLineItems (optional)
  • line_item_id (required)
  • Quantity (required)
  • Sku (optional)
  • Description (required)
  • Unit_cost (required)
  • Event_id (optional)
• DeleteInvoiceLineItems (optional)
  • line_item_id (required)

Output

For each Invoice ID, success or failure.

Example Request

<EditInvoicesRequest>
      <Invoices>
           <Invoice invoice_id="741" request_id="a1b2c3">
                <QuoteOrInvoice>Invoice</QuoteOrInvoice>
                <ExternalID>1234</ExternalID>
                <SalesRepContactID>123</SalesRepContactID>
                <Group_id>8</Group_id>
                <Due_date>20120321</Due_date>
                <InvoiceType>30 Day</InvoiceType>
                <InvoiceStatus>PAID</InvoiceStatus>
                <ShipmentAdvancedDaysWorkflow>2</ShipmentAdvancedDaysWorkflow>
                <ShipmentWorkflowID>1</ShipmentWorkflowID>
                <ShipmentDate>2012-03-01</ShipmentDate>
                <ShipToName>Jeff Gordon</ShipToName>
                <ShipToAddress>1 Gordon Road, Gordon Street</ShipToAddress>
                <ShipToCity>Easy Gordon</ShipToCity>
                <ShipToState>CA</ShipToState>
                <ShipToZip>12345</ShipToZip>
                <ShipToCountry>United States</ShipToCountry>
                <ShipToPhone>+12015550123</ShipToPhone>
                <ShippingMethod>USPS</ShippingMethod>
                <Description>Sample Invoice 1</Description>
                <InvoiceFooter><![CDATA[<p>The <strong>quick </strong><em>brown </em><u>fox </u>jumps over the lazy dog.</p><p>The <strong>quick </strong><em>brown </em><u>fox </u>jumps over the lazy dog.</p>]]></InvoiceFooter>
                <Paid_date>201203121423</Paid_date>
                <TransactionID>1234554321</TransactionID>
                <Payment_amount>50.00</Payment_amount>
                <AddInvoiceLineItems>
                    <InvoiceLineItem>
                        <Quantity>3</Quantity>
                        <Description>My Test Service</Description>
                        <Sku>1111</Sku>
                        <Unit_cost>10.00</Unit_cost>
                    </InvoiceLineItem>
                    <InvoiceLineItem>
                        <Quantity>3</Quantity>
                        <Description>Another Test Service</Description>
                        <Sku>2222</Sku>
                        <Unit_cost>10.00</Unit_cost>
                    </InvoiceLineItem>
                </AddInvoiceLineItems>
                <EditInvoiceLineItems>
                    <InvoiceLineItem line_item_id="68">
                        <Quantity>3</Quantity>
                        <Description>My Test Service</Description>
                        <Sku>1111</Sku>
                        <Unit_cost>10.00</Unit_cost>
                    </InvoiceLineItem>
                    <InvoiceLineItem line_item_id="69">
                        <Quantity>3</Quantity>
                        <Description>My Other Test Service</Description>
                        <Sku>2222</Sku>
                        <Unit_cost>10.00</Unit_cost>
                    </InvoiceLineItem>
                </EditInvoiceLineItems>
                <DeleteInvoiceLineItems>
                    <InvoiceLineItem line_item_id="70"></InvoiceLineItem>
                    <InvoiceLineItem line_item_id="71"></InvoiceLineItem>
                </DeleteInvoiceLineItems>
           </Invoice>
           <Invoice invoice_id="742" request_id="d4e5f6">
                <QuoteOrInvoice>Quote</QuoteOrInvoice>
                <SalesRepContactID>123</SalesRepContactID>
                <Group_id>9</Group_id>
                <Due_date>20120323</Due_date>
                <InvoiceType>30 Day</InvoiceType>
                <InvoiceStatus>UNPAID</InvoiceStatus>
                <ShipmentAdvancedDaysWorkflow>2</ShipmentAdvancedDaysWorkflow>
                <ShipmentWorkflowID>1</ShipmentWorkflowID>
                <ShipmentDate>2012-03-01</ShipmentDate>
                <ShippingMethod>USPS</ShippingMethod>
                <Description>Sample Invoice 2</Description>
                <InvoiceFooter>The quick brown fox jumps over the lazy dog.</InvoiceFooter>
           </Invoice>
      </Invoices>
 </EditInvoicesRequest>

Example Request (Mark an invoice as paid)

<EditInvoicesRequest>
      <Invoices>
           <Invoice invoice_id="741">
                <Paid_date>201203121423</Paid_date>
                <TransactionID>1234554321</TransactionID>
                <Payment_amount>50.00</Payment_amount>
           </Invoice>
      </Invoices>
 </EditInvoicesRequest>

Successful Response

<EditInvoicesResponse>
      <Invoices>
           <Invoice request_id="a1b2c3">
                <Result>Success</Result>
                <InvoiceID>741</InvoiceID>
                <AddInvoiceLineItems>
                    <InvoiceLineItem>
                        <Result>Success</Result>
                        <LineItemID>73</LineItemID>
                    </InvoiceLineItem>
                    <InvoiceLineItem>
                        <Result>Success</Result>
                        <LineItemID>74</LineItemID>
                    </InvoiceLineItem>
                </AddInvoiceLineItems>
                <EditInvoiceLineItems>
                    <InvoiceLineItem>
                        <Result>Success</Result>
                        <LineItemID>68</LineItemID>
                    </InvoiceLineItem>
                    <InvoiceLineItem>
                        <Result>Error</Result>
                        <ErrorCode>3401</ErrorCode>
                        <ErrorText>Line item #69 does not exists</ErrorText>
                    </InvoiceLineItem>
                </EditInvoiceLineItems>
                <DeleteInvoiceLineItems>
                    <InvoiceLineItem>
                        <Result>Success</Result>
                        <LineItemID>70</LineItemID>
                    </InvoiceLineItem>
                    <InvoiceLineItem>
                        <Result>Success</Result>
                        <LineItemID>71</LineItemID>
                    </InvoiceLineItem>
                </DeleteInvoiceLineItems>
           </Invoice>
           <Invoice request_id="d4e5f6">
                <Result>Success</Result>
                <InvoiceID>742</InvoiceID>
           </Invoice>
      </Invoices>
 </EditInvoicesResponse>

Delete Invoices

This function allows the caller to delete one or more invoices from the database.

Input

Specify search criteria within each invoice tag. Search criteria can be:

• request_id (optional)
• invoice_id
• contact_id
• contact_firstname
• contact_lastname

Each invoice’s search criteria must return a single unique invoice to modify.

Output

For each Invoice ID, success or failure.

Example Request

<DeleteInvoicesRequest>
      <Invoices>
           <Invoice invoice_id="1221" request_id="a1b2c3" />
           <Invoice invoice_id="1222" request_id="d4e5f6" />
      </Invoices>
 </DeleteInvoicesRequest>

Successful Response

<DeleteInvoicesResponse>
      <Invoices>
           <Invoice request_id="a1b2c3">
                <Invoice_id>1221</Invoice_id>
                <Result>Success</Result>
           </Invoice>
           <Invoice request_id="d4e5f6">
                <Invoice_id>1222</Invoice_id>
                <Result>Success</Result>
           </Invoice>
      </Invoices>
 </DeleteInvoicesResponse>