README

UltraCart REST API Version 2

This PHP package is automatically generated by the Swagger Codegen project:

API version: 2.0.0
Build package: io.swagger.codegen.languages.PhpClientCodegen For more information, please visit http://www.ultracart.com

Requirements

PHP 5.5 and later

Installation & Usage

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/ultracart/rest_api_v2_sdk_php.git"
    }
  ],
  "require": {
    "ultracart/rest_api_v2_sdk_php": "*@dev",
    "guzzlehttp/guzzle": "~6.0"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

    require_once('/path/to/vendor/whatever_you_named_your_ultracart_sdk_directory/autoload.php');

Tests

To run the unit tests:

composer install
./vendor/bin/phpunit

Getting Started

Please follow the installation procedure and then run the following:

<?php

require_once __DIR__ . '/vendor/autoload.php';

// Create a Simple Key: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/38688545/API+Simple+Key
$simple_key = '109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00';
$api_instance = ultracart\v2\api\OrderApi::usingApiKey($simple_key);

// The UltraCart objects are large.  Very large.  So we have encapsulated the fields in sub objects allowing you to
// only request the sub objects you need.  This is done via the expansion object.   The API docs on the main web site
// have more details about expansions:  https://www.ultracart.com/api/#expansion.html
$_expand = "affiliate,affiliate.ledger,auto_order,billing,buysafe,channel_partner,checkout,coupon,customer_profile,digital_order,edi,fraud_score,gift,gift_certificate,internal,item,linked_shipment,marketing,payment,payment.transaction,quote,salesforce,shipping,summary,taxes"; // string | The object expansion to perform on the result.

// this is a detailed example that includes chunking to illustrate how to fetch large record sets from UltraCart.
$_limit = 100;
$counter = 1;
$order_query = new \ultracart\v2\models\OrderQuery();
// we are essentially setting the dates to 'forever' to get all records.
$order_query->setPaymentDateBegin("2010-01-01T00:00:00.0000000-05:00");
$order_query->setPaymentDateEnd("2021-01-01T00:00:00.0000000-05:00");
// there are multiple stages for order flow.  when doing analysis, you almost always want *only* completed orders.
$order_query->setCurrentStage(\ultracart\v2\models\OrderQuery::CURRENT_STAGE_COMPLETED_ORDER);

$order_response = null;

echo "<html><body><pre>";
try {
    do {
        if ($order_response == null) {
            $order_response = $api_instance->getOrdersByQuery($order_query, $_limit, 0, null, $_expand);
        } else {
            $order_response = $api_instance->getOrdersByQuery($order_query, $_limit, $order_response->getMetadata()->getResultSet()->getNextOffset(), null, $_expand);
        }

        echo "order_response.Orders.length: " . sizeof($order_response->getOrders()) . "\n";
        // print out a line for each order *item*
        // notice, email is within the billing child object.
        foreach ($order_response->getOrders() as $order) {
            $order_id = $order->getOrderId();
            $email = $order->getBilling()->getEmail(); // notice the email is part of the billing sub object.
            foreach($order->getItems() as $item){
                echo $order_id . ',' . $email . ',' . $item->getMerchantItemId() . ',' . $item->getQuantity() . "\n";
            }
        }
    } while ($order_response->getMetadata()->getResultSet()->getMore());

} catch (Exception $e) {
    echo 'Exception when calling OrderApi->getOrdersByQuery: ', $e->getMessage(), PHP_EOL;
}
echo "</pre></body></html>";
?>

Automatic Retry (v3.0.62, January 2021)

Starting with 3.0.62, we have modified the standard SDK to include retry logic. This logic was handled to allow client code to automatically retry if it trips the server side rate limiter

Usage

Set the MaxRetyAfter (seconds) within the Configuration object. This is a failsafe to avoid having client code hang forever if the retry-after header returns a large number. If you don't mind your code waiting for an hour, then you may set the retry to 3600, etc.

ultracart\v2\Configuration::getDefaultConfiguration()->setMaxRetrySeconds(30);

This is the actual logic used to determine if a retry should be attempted:

try {
    $response = $this->client->send($request, $options);
} catch (RequestException $e) {

    // BEGIN Retry Logic
    if($e->getResponse()) {
        $retryAfter = 0;
        if (array_key_exists('Retry-After', $headers)) {
            $retryAfter = intval($headers['Retry-After'][0]);
        }

        if ($statusCode == 429 && $retry && $retryAfter > 0 && $retryAfter <= $this->config->getMaxRetrySeconds()) {
            sleep($retryAfter);
            return $this->getCustomersByQueryWithHttpInfoRetry(false, $customer_query, $_limit, $_offset, $_since, $_sort, $_expand);
        }
    }
    // End Retry Logic

    throw new ApiException(
        "[{$e->getCode()}] {$e->getMessage()}",
        $e->getCode(),
        $e->getResponse() ? $e->getResponse()->getHeaders() : null,
        $e->getResponse() ? $e->getResponse()->getBody()->getContents() : null
    );
}

Documentation for API Endpoints

All URIs are relative to https://secure.ultracart.com/rest/v2

Documentation For Models

Documentation For Authorization

ultraCartBrowserApiKey

Type: API key
API key parameter name: x-ultracart-browser-key
Location: HTTP header

ultraCartOauth

Type: OAuth
Flow: accessCode
Authorization URL: https://secure.ultracart.com/rest/v2/oauth/authorize
Scopes:
affiliate_read: Allows you to read affiliate information.
affiliate_write: Allows you to write affiliate information.
auto_order_read: Allows you to read auto order information.
auto_order_write: Allows you to write auto order information.
channel_partner_read: Allows you to read channel partner information.
channel_partner_write: Allows you to write channel partner information.
chargeback_read: Allows you to read chargeback information.
chargeback_write: Allows you to write chargeback information.
checkout_read: Allows you to read checkout information.
checkout_write: Allows you to write checkout information.
configuration_read: Allows you to read configuration information.
configuration_write: Allows you to write configuration information.
conversation_read: Allows you to read conversation information.
conversation_write: Allows you to write conversation information.
coupon_read: Allows you to read coupon information.
coupon_write: Allows you to write coupon information.
customer_read: Allows you to read customer information.
customer_write: Allows you to write customer information.
fulfillment_read: Allows you to read fulfillment information.
fulfillment_write: Allows you to write fulfillment information.
gift_certificate_read: Allows you to read gift certificate information.
gift_certificate_write: Allows you to write gift certificate information.
integration_log_read: Allows you to read integration log information.
integration_log_write: Allows you to write integration log information.
order_read: Allows you to read order information.
order_write: Allows you to write order information.
item_read: Allows you to read item information.
item_write: Allows you to write item information.
storefront_read: Allows you to read storefront information.
storefront_write: Allows you to write storefront information.
tax_read: Allows you to read tax configuration information.
tax_write: Allows you to write tax configuration information.
webhook_read: Allows you to read webhook information.
webhook_write: Allows you to write webhook information.
ultrabooks_read: 1 of 2 required to use UltraBooks
ultrabooks_write: 2 of 2 required to use UltraBooks
user_read: Allows you to read user information.
user_write: Allows you to write user information.
workflow_read: Allows you to read workflow information.
workflow_write: Allows you to write workflow information.

ultraCartSimpleApiKey

Type: API key
API key parameter name: x-ultracart-simple-key
Location: HTTP header

Author

support@ultracart.com

CHANGE LOG

Not every change is committed to every SDK.

Some changes jump version numbers due to multiple commits for bug fixes, omissions, and errors. At UltraCart, we eat our own dog food, and we increment the version number for every commit in order to generate a new javascript npm. For this reason, version gaps will be found in the change log above.

ultracart / rest_api_v2_sdk_php

Maintainers

Details