Integration with your administration (preferred implementation)

The API serves to simplify and automate the processes that take place after an invoice is created. This API provides all the invoice operations that can be made from the e-shop administration This is a preferred way of implementation which allows the eshop to fully automate all processes.

There are four actions changing the invoice status are: activating, canceling, editing and returning the invoice items. The availability of these actions depends on the status of the invoice. Once activated, the invoice can’t be edited or canceled. Instead, you can only report a return.

Anytime:

getting data
invoice list

Before activating the invoice:

activating the invoice
cancelling the invoice
editing the invoice
splitting the invoice

After activating the invoice:

reporting a return of the invoice
cancelling reported return of the invoice
returning part of the invoice
returning the entire invoice
lowering the invoice price

Warning: All error states may end up in error. This may be a data validation error, unauthorized invoice status, or an internal server error. In these cases, the response status code is 400 or 500 and in addition, the library raises an exception. If the API is linked to an action on your e-shop, it is advisable to make an API call before saving the data to the database and in the case of an API error, the action will be canceled and the user will see an error message.

Getting data

Obtaining current invoice data is possible by sending GET request in the library by calling the method GET. This is possible at any time regardless of the invoice status.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->get();

echo $invoice->pdf_url;
?>

Response contains all the information that appears on the invoice in the e-shop administration.

Note: All actions return updated data in response. Therefore, no need to call the get method in the library after a successful action.

Activating the invoice

Activation of the invoice is made at the time of dispatching the order from the e-shop to customer. Activation will automatically set the due date and generate the PDF invoice with payment instructions for the customer. Part of the response is the pdf_url address from which you can download the PDF invoice file. An invoice can only be activated once, otherwise the API will return an error. Also, you cannot activate a canceled invoice.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->activate();

echo $invoice->pdf_url;
?>

Cancelling the invoice

You can only cancel an invoice that is not activated or canceled, otherwise the API returns an error.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->cancel();
?>

Editing the invoice

You can only edit an invoice that is not activated or canceled, otherwise the API returns an error. It is allowed to edit only the items of the order. The request must include all invoice items in the field items. Items are matched by the attribute product_id. After the request is submitted, items are overwritten. Items that were part of the invoice but not in the request will be deleted. If you only want to add an item, you must also list all other items.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

// enough to fill only the items field, it is not necessary to have loaded all the invoice data
$invoice->items = array(
    new Twisto\Item(
        Twisto\Item::TYPE_DEFAULT,                  // type
        'Agatha Christie: The Secret Adversary',    // name
        942,                                        // product_id
        1,                                          // quantity
        285.31,                                     // price_vat
        15,                                         // vat
        null,                                       // ean_code
        '9781609421052'                             // isbn_code
    ),
    new Twisto\Item(
        Twisto\Item::TYPE_SHIPMENT,     // type
        'Doprava DPD',                  // name
        'shipment',                     // product_id
        1,                              // quantity
        119,                            // price_vat
        21                              // vat
    ),
    new Twisto\Item(
        Twisto\Item::TYPE_PAYMENT,                  // type
        'Twisto Faktura – platím až po vyzkoušení', // name
        'payment',                                  // product_id
        1,                                          // quantity
        0,                                         // price_vat
        21                                          // vat
    ),
);
$invoice->save();

// after saving, the total invoice price was recalculated
echo $invoice->total_price_vat;
?>

Splitting the invoice

Splitting invoices is used for cases where a part of the goods from the original order will be shipped earlier than the rest, and both should, therefore, have a different date due.

Splitting is allowed only for customers who have this feature enabled (this feature is currently disabled for your eshop). Please contact us for activation or deactivation of this feature.

Only invoices which are not yet activated and have more than one item (quantity) of goods can be divided. Only goods can be divided into a new invoice. In the case that you’d like to add shipping fee to the newly created invoice, you can use edit invoice. A maximum number of invoice splits is not restricted. However, the invoices that were created using split invoice cannot be divided any further.

<?php
$invoice = new Twisto\Invoice($twisto, '123');

// defining items which should be divided into separate invoice
// dividing 4 items with product_id 123 and one item with product_id 432 into new invoice
$items = array(
    new Twisto\ItemSplit("123", 4)
    new Twisto\ItemSplit("432", 1)
);

// the object `$split_invoice` will contain a new invoice
$split_invoice = $invoice->splitItems($items);
?>

Reporting a return of the invoice

Reports an incoming return of the invoice. Prolongs the invoice payment due date. This feature is not allowed by default.

<?php
$invoice = new Twisto\Invoice($twisto, '123');
$invoice->reportReturn();
?>

Cancelling reported return of the invoice

Once the invoice return was reported and not done yet, it is possible to cancel the reported return if the reported invoice is eligible.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');
$invoice->cancelReportReturn();
?>

Returning part of the invoice

Return items are only available for activated invoices. Only items of goods, discounts and shipping (TYPE_DEFAULT, TYPE_DISCOUNT a TYPE_SHIPMENT) are eligible to be returned. Shipping and payment items are marked as returned automatically when all items are returned. For discount (TYPE_DISCOUNT) items, you can change the price, but only if the number of pieces (quantity) is 1. If the item has a discount of more than 1, it is not possible to change the price.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

$invoice->returnItems(
    // returning 1 item with product_id 942
    array(new Twisto\ItemReturn(942, 1)),

    // changing the price of the discount item to -42 Kč with product_id 852
    array(new Twisto\ItemDiscountReturn(852, -42))
);

// after the return is made, the total invoice price was recalculated
echo $invoice->total_price_vat;
?>

Returning the entire invoice

Only an activated invoice can be returned.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

$invoice->returnAll();
?>

Lowering the invoice price

Lowering the price is possible only for activated invoices. This method is intended for refunding part or whole invoice in cases where using item IDs is not possible.

Lowering the price of an invoice is allowed only for customers who have this feature enabled (this feature is enabled for your eshop). Please contact us for activation or deactivation of this feature.

Price of the invoice can only be lowered by a positive amount that is lower or equal to the total price of the invoice.

<?php
$invoice = new Twisto\Invoice($twisto, '10123456');

$invoice->refund(
    // Lowering the invoice price by 12.34 Kč
    12.34
);
?>

Invoice list

Listing and search in all invoices. Max items per page is 100, next contains link to next page and previous to previous page.

Query params for searching

Name	Maximum length	Value
date_from	ISO 8601	Search for invoices with date equal or greater than this
date_to	ISO 8601	Search for invoices with date equal or lower than this
invoice_id	10	Twisto Invoice ID
eshop_invoice_id	10	Eshop invoice ID. If filled, It will be used as a variable code to send a payment to your e-shop account. Only digits are allowed.
external_id	50	E-shop order/invoice ID. If filled, it will be returned in API responses and it will appear in XLSX Overview.
customer_email	254	Customer email
provider_id	254	Payment provider order ID. Format EYDDDNNNNNNNN is required.

{
  "next": "http://api.twisto.cz/v2/invoice/list/?cursor=cD00NjQ%3D",
  "previous": null,
  "results": [
    {
      "invoice_id": "19383193",
      "eshop_invoice_id": "",
      "customer_email": "gigatest9@twisto.cz",
      "date_created": "2018-02-05T00:00:00Z",
      "date_returned": "2018-02-28T11:14:00Z",
      "date_cancelled": null,
      "date_activated": "2018-02-05T00:00:00Z",
      "date_paid": null,
      "date_due": "2018-03-01",
      "initial_date_due": "2018-03-01",
      "total_price_vat": "0.00",
      "pdf_url": "http://api.twisto.cz/invoice/pdtk31vk3lt0uocq1ws679n4cbb5ecxoo8yafncifs7qmip40l/19383193.pdf"
    }
  ]
}

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: your-public-key,your-security-key" \
'https://api.twisto.cz/v2/invoice/list/'