schedules.update

Updates an existing schedule. It also allows you to create a new client and/or items in the same request.

If the client name does not exist a new one is created.

Regarding item taxes, if the tax name is not found, it is ignored and no tax is applied to that item.

If no item exists with the given name a new one will be created.

If the item exists it will be updated with the new values

Be careful when updating the schedule items, as any missing items from the original invoice are deleted.

You call this method by submitting a HTTP PUT request to the following URL with the invoice updates on xml format in the request body:

https://screen-name.invoicexpress.net/schedules/:schedule-id.xml

Example xml to be submitted with the updated schedule data:

<?xml version="1.0" encoding="UTF-8"?>
  <schedule>
    <start_date>30/10/2009</start_date>
    <end_date>30/10/2020</end_date>
    <create_back>Yes</create_back>
    <schedule_type>Monthly</schedule_type>
    <interval>2</interval>
    <send_to_client>Yes</send_to_client>
    <description>One description</description>
    <invoice_template>
      <due_days>0</due_days>
      <reference></reference>
      <observations></observations>
      <retention></retention>
      <client>
        <name>Client</name>
        <email>client@email.com</email>
        <address></address>
        <postal_code></postal_code>
        <fiscal_id></fiscal_id>
      </client>
      <items type="array">
        <item>
          <name>Product x</name>
          <description></description>
          <unit_price>0.0</unit_price>
          <quantity>3.0</quantity>
          <tax>
            <name>IVA20</name>
          </tax>
          <discount>0.0</discount>
        </item>
        <item>
          <name>Product y</name>
          <description></description>
          <unit_price>0.0</unit_price>
          <quantity>3.0</quantity>
          <tax>
            <name>IVA20</name>
          </tax>
          <discount>0.0</discount>
        </item>
      </items>
   </invoice_template>
</schedule>

Parameters

Parameters are the data you will pass with the call.

api_key

Your secret identifier. Your API Key is on Account Overview in the Account section.
Rules: Required

start_date

Date your schedule starts.
Rules: Required. Date must be in format dd/mm/yyyy. Example: 12/03/2009

end_date

Date your schedule ends.
Rules: Required. Date must be format dd/mm/yyyy. Example: 12/03/2009. Must be later than start_date

create_back

Tells Invoic€xpress to create all the invoices between the schedule start_date and the current date.
Rules: Optional. Options are:

Yes – Create the invoices
No – Don’t create the invoices (also the default)

schedule_type

Schedule interval unit.
Rules: Required. Options are:

Daily – interval is measured in days
Monthly – interval is measured in months
Yearly – interval is measured in years

interval

The schedule periodicity.
Rules: Required. Must be a number equal or greater than 0

send_to_client

If this option is set to Yes, in the scheduled dates, the invoice is automatically created, finalized and sent to client. Otherwise only a draft is created
Rules: Required

description

Schedule description.
Rules: Required

invoice_template / due_days

Days between each invoice date and due_date.
Rules: Required. Must be a number and equal or greater than 0.

invoice_template / reference

Reference, usually a purchase order.
Rules: Optional

invoice_template / observations

Observations , these will be printed with the invoice.
Rules: Optional

invoice_template / retention

Withholding tax percentage (%)
Rules: Optional. Must be a number between 0 and 99.99

invoice_template / client / name

Client name. If the client doesn’t exist a new one will be created. If it exists the remaining client fields will be ignored.
Rules: Required

invoice_template / client / email

Client email.
Rules: Optional. Must be a valid email address ex:foo@bar.com

invoice_template / client / address

Client address, normally used for a company address.
Rules:Optional.

invoice_template / client / postal_code

Client postal code, normally used for a company postal code.
Rules: Optional.

invoice_template / client / fiscal_id

Client fiscal id.
Rules: Optional.

invoice_template / items

An array of invoice items.

If items with the given names do not exist, they are created.
If an item already exists, it is updated with the new values.

Rules: At least one item is required.

invoice_template / item / name

Item name.
Rules: Required

invoice_template / item / description

Item description.
Rules: Optional

invoice_template / item / unit_price

Item unit_price.
Rules: Required. Needs to be greater than 0.0.

invoice_template / item / quantity

Item quantity.
Rules: Required. Needs to be greater than 0.0.

invoice_template / item / discount

Item discount.
Rules: Optional. Defaults to 0.0. If present needs to be greater or equal than 0.0 and less or equal than 100.0

invoice_template / item / tax

The item tax.
Rules: Optional. If not present no tax will be applied to the item

invoice_template / item / tax / name

Item tax name.
Rules: Optional. If not found no tax is applied to the item

Return Values

This is the result that will be passed back to you when you have sent a call.

Success

HTTP: 200 OK

Error

HTTP: 401 Access denied
The API Key parameter is missing or incorrect.

HTTP: 404 Not Found
No schedule matches the supplied :schedule-id

HTTP: 422 Unprocessable Entity
Some parameters were incorrect.

Possible errors:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Retention must be a number between 0 and 99.99</error>
 <error>Invoice items is invalid</error>
 <error>Client is invalid</error>
 <error>email must be an email address</error>
 <error>discount is not a number</error>
 <error>quantity must be a number greater than 0</error>
 <error>unit_price must be a number</error>
</errors>

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Can't update an archived schedule</error>
</errors>