Posting data to the Bulk Connection API will create a background job that will be processed in the order that jobs are received.

📘

Bulk API Email Notifications

Once in Production, the API can send email notifications with the results of the job. Please provide your email address to your Integrations Manager to set up these notifications.

🚧

Adding New Customers

Please allow approximately 72 hours for client customer data to be matched to the JOOR database.

  • 0-400 customers --> 24-48 hours
  • 400-1000 customers --> 72 hours
  • 1000+ customers --> 5 business days (preferable to send on Monday)

If testing in Sandbox, please inform your Integration Manager when you have pushed new customers in order for the connections to be established.

🚧

Customer Data Prerequisites

Before beginning to test the integration, you will need to configure the following information in your account if you plan on including it in your customer data. All fields are optional unless otherwise noted.

  • Currencies and price labels (required)
  • Currency/price label combination must be unique. Currency/price label combinations assigned to customers must exactly match the currency/price label used at the style level.
  • Payment method terms and codes
  • Shipping method terms and codes
  • Sales representative names, codes, and emails
  • The relationship between sales rep email and code is 1 to 1. Each sales rep email address can only be associated with one unique sales rep code.
  • Warehouse names and codes
  • Customer group names and codes
  • Company number names and codes

👍

Endpoint

Params

  • Accept: application/xml OR application/json
  • Content-Type: application/xml OR application/json
  • Authorization: OAuth2 [Base64 encoded token]

Request Detail

FIELD NAME REQ VALUE MAX DISPLAY DESCRIPTION
+ bulk_connectionsnode : 1-1
  + connectionnode : 1-n
    customer_name Y Any String 100 Y The name of the customer as it is intended to be displayed
    customer_code Y Any String 50 Y The clients unique identifier for the specified customer
    customer_alias N Any String 150 Y Custom name supplied by the Brand to identify a connection on JOOR
    company_number_name N Any String 150 Y The name of the group of retailers to which the customer belongs
    company_number_code N Any String 100 Y The code associated with the company
    customer_group_name Highly Recommended Any String 150 Y The name of customer group
    customer_group_code N Any String 100 Y The code associated with the customer group
    customer_phone N Any String 50 Y The primary phone number used for contacting the customer
    customer_contact N Any String 50 Y The name of the primary contact for the customer
    customer_contact_email N Any String 50 Y The email for the primary contact for the customer
    sales_rep_code Highly Recommended Any String 50 Y The code for the sales representative. Only one can be provided.
    + buyersnode : 0-1
      + buyernode : 1-n
        buyer_name Y Any String 50 Y The buyer's full name
        buyer_title N Any String 50 Y The buyer's title or position within the customer organization
        buyer_email Y Any String 50 Y The buyer's email address
        buyer_phone N Any String 50 Y The buyer's phone number including extension information
        buyer_fax N Any String 50 Y The buyer's fax number
    + shippingnode : 0-1
      + shipping_addressesnode : 0-1
        + shipping_addressnode : 1-n
          shipping_name N Any String 50 Y The name to address for shipping. If blank, customer name will be used
          shipping_code Y Any String 50 Y The code assigned to the shipping address.
          shipping_phone N Any String 50 Y The phone for the shipping address
          shipping_address_1 N Any String 50 Y The street address for the shipping address
          shipping_address_2 N Any String 50 Y The secondary address information for the shipping address
          shipping_city Y Any String 50 Y The city of the shipping address
          shipping_state N Any String 50 Y The state, province or region of the shipping address
          shipping_postal_code N Any String 50 Y The postal or zip code of the shipping address
          shipping_country Y Any String 50 Y The country of the shipping address. Country name must be listed in English or in ISO Code format.
          shipping_create_doors N Boolean Y True if a door should be created for this shipping address, false if a door should not be created. If field is not included, default is false. Will create door with name format "Shipping Name - Shipping Code" and door code "Shipping Code".
      + shipping_methodsnode : 0-1
        + shipping_methodnode : 1-n
          shipping_method_name N Any String 50 Y The shipping method name available to the customer
          shipping_method_code N Any String 50 Y The shipping method code available to the customer
    + billingnode : 0-1
      + billing_addressesnode : 0-1
        + billing_addressnode : 1-n
          billing_name N Any String 50 Y The name to address for billing. If blank customer name will be used.
          billing_code Y Any String 50 Y The code assigned to the billing address.
          billing_phone N Any String 50 Y The phone for the billing address
          billing_address_1 N Any String 50 Y The street address of the billing address
          billing_address_2 N Any String 50 Y The secondary address information for the billing address
          billing_city Y Any String 50 Y The city of the billing address
          billing_state N Any String 50 Y The state, province or region of the billing address
          billing_postal_code N Any String 50 Y The postal or zip code of the billing address
          billing_country Y Any String 50 Y The country of the billing address. Country name must be listed in English or in ISO Code format.
      + payment_methodsnode : 0-1
        + payment_methodnode : 1-n
          payment_method_name N Any String 50 Y The payment method name available to the customer
          payment_method_code N Any String 50 Y The payment method code available to the customer
    + customer_locationsnode : 0-1
        + customer_locationnode : 1-n
          location_phone N Any String 50 Y The phone for the customer location
          location_address_1 N Any String 50 Y The street address of the location address
          location_address_2 N Any String 50 Y The secondary address information for the location address
          location_city Y Any String 50 Y The city of the location address
          location_state N Any String 50 Y The state, province or region of the location address
          location_zip N Any String 50 Y The postal or zip code of the location address
          location_country Y Any String 50 Y The country of the location address. Country name must be listed in English or in ISO Code format.
    + price_typesnode : 1-n
        + price_typenode : 1-n
        price_type_currency_code Y Any String 50 Y The code of the price type currency to assign to the customer
        price_type_label Y Any String 50 Y The name of the price type to assign to the customer
        price_type_retail_currency_code Y Any String 50 Y The name of the retail price type currency to assign to the customer
    + discountsnode : 0-1
      + discountnode : 1-n
        amount Highly Recommended Decimal Y Percent
        line_item_level N Boolean Y True if discount is on the line item level, False if discount is on the Order level
    + warehousesnode : 1-1
      + warehousenode : 1-n
        warehouse_code N Any String 50 Y The code of the warehouse to assign to the customer
        warehouse_name N Any String 50 Y The name of the warehouse to assign to the customer

Response Detail

FIELD NAMETYPEDESCRIPTION
bulk_connections_job_idIntegerA JOOR unique identifier for the bulk connections job
statusString"queued", "started", "finished"
connection_record_countIntegerNumber of connections that are in the job
connection_record_progressIntegerConnection record number, if the job has been started

Request Example

<?xml version="1.0" encoding="UTF-8"?>
<bulk_connections>
    <connection>
        <customer_code>JBNY</customer_code>
        <customer_alias>Alias</customer_alias>
        <customer_name>JboutiqueNY</customer_name>
        <customer_email>[email protected]</customer_email>
        <customer_contact_name>Kristen Leone</customer_contact_name>
        <company_number_name>Company1</company_number_name>
        <company_number_code>c1</company_number_code>
        <customer_group_name>Specialty</customer_group_name>
        <customer_group_code>SPC</customer_group_code>
        <sales_rep_code>AB</sales_rep_code>
        <warehouses>
            <warehouse>
                <warehouse_name>Test Warehouse</warehouse_name>
                <warehouse_code>Test Code</warehouse_code>
            </warehouse>
        </warehouses>
        <buyers>
            <buyer>
                <buyer_name>Test Buyer</buyer_name>
                <buyer_email>[email protected]</buyer_email>
            </buyer>
        </buyers>
        <billing>
            <billing_addresses>
                <billing_address>
                    <billing_code>JBNY01</billing_code>
                    <billing_name>JboutiqueNY</billing_name>
                    <billing_phone>2018926148</billing_phone>
                    <billing_address_1>708 Willow Ave</billing_address_1>
                    <billing_address_2>Suite 5F</billing_address_2>
                    <billing_city>Hoboken</billing_city>
                    <billing_state>NJ</billing_state>
                    <billing_postal_code>07030</billing_postal_code>
                    <billing_country>France</billing_country>
                </billing_address>
                <billing_address>
                    <billing_code>JBNY02</billing_code>
                    <billing_name>JboutiqueNY</billing_name>
                    <billing_phone>0000000000</billing_phone>
                    <billing_address_1>1 Main St</billing_address_1>
                    <billing_address_2 />
                    <billing_city>New York</billing_city>
                    <billing_state>NY</billing_state>
                    <billing_postal_code>10005</billing_postal_code>
                    <billing_country>United States</billing_country>
                </billing_address>
            </billing_addresses>
            <payment_methods>
                <payment_method>
                    <payment_method_name>Net 30 (Pending Approval)</payment_method_name>
                    <payment_method_code>net30</payment_method_code>
                </payment_method>
                <payment_method>
                    <payment_method_name>Credit Card</payment_method_name>
                    <payment_method_code>cc</payment_method_code>
                </payment_method>
                <payment_method>
                    <payment_method_name>Wire Transfer</payment_method_name>
                    <payment_method_code>wt</payment_method_code>
                </payment_method>
            </payment_methods>
        </billing>
        <shipping>
            <shipping_addresses>
                <shipping_address>
                    <shipping_code>JBNY1</shipping_code>
                    <shipping_name>JboutiqueNY</shipping_name>
                    <shipping_phone>212-555-1212</shipping_phone>
                    <shipping_email>[email protected]</shipping_email>
                    <shipping_address_1>1 Main St</shipping_address_1>
                    <shipping_address_2 />
                    <shipping_city>New York</shipping_city>
                    <shipping_state>NY</shipping_state>
                    <shipping_postal_code>10005</shipping_postal_code>
                    <shipping_country>United States</shipping_country>
                    <shipping_create_doors>True</shipping_create_doors>
                </shipping_address>
                <shipping_address>
                    <shipping_code>JBNY2</shipping_code>
                    <shipping_name>JboutiqueNY</shipping_name>
                    <shipping_phone>(713) 780-8564</shipping_phone>
                    <shipping_email>[email protected]</shipping_email>
                    <shipping_address_1>1 Main St</shipping_address_1>
                    <shipping_address_2 />
                    <shipping_city>New York</shipping_city>
                    <shipping_state>NY</shipping_state>
                    <shipping_postal_code>10005</shipping_postal_code>
                    <shipping_country>United States</shipping_country>
                    <shipping_create_doors>False</shipping_create_doors>
                </shipping_address>
            </shipping_addresses>
            <shipping_methods>
                <shipping_method>
                    <shipping_method_name>UPS Ground</shipping_method_name>
                    <shipping_method_code>ups_ground</shipping_method_code>
                </shipping_method>
                <shipping_method>
                    <shipping_method_name>UPS 2-Day</shipping_method_name>
                    <shipping_method_code>ups_2day</shipping_method_code>
                </shipping_method>
                <shipping_method>
                    <shipping_method_name>FedEx International Economy</shipping_method_name>
                    <shipping_method_code>fedex_economy</shipping_method_code>
                </shipping_method>
            </shipping_methods>
        </shipping>
        <price_types>
            <price_type>
                <price_type_label>Europe</price_type_label>
                <price_type_currency_code>EUR</price_type_currency_code>
                <price_type_retail_currency_code>EUR</price_type_retail_currency_code>
            </price_type>
            <price_type>
                <price_type_label>Australia</price_type_label>
                <price_type_currency_code>AUD</price_type_currency_code>
                <price_type_retail_currency_code>USD</price_type_retail_currency_code>
            </price_type>
        </price_types>
        <customer_locations>
            <customer_location>
                <location_address_1>1 Main St</location_address_1>
                <location_address_2 />
                <location_city>New York</location_city>
                <location_state>NY</location_state>
                <location_zip>10005</location_zip>
                <location_country>United States</location_country>
                <location_phone>212-555-1212</location_phone>
            </customer_location>
        </customer_locations>
        <discounts>
            <discount>
                <amount>4.0</amount>
                <line_item_level>True</line_item_level>
            </discount>
        </discounts>
    </connection>
    <connection>
        ...
    </connection>
</bulk_connections>
{
  "bulk_connections": {
    "connection": [
      {
        "customer_code": "JBNY",
        "customer_alias": "Alias",
        "customer_name": "JboutiqueNY",
        "customer_email": "[email protected]",
        "customer_contact_name": "Kristen Leone",
        "company_number_name": "company1",
        "company_number_code": "c1",
        "customer_group_name": "Specialty",
        "customer_group_code": "SPC",
        "sales_rep_code": "AB",
        "warehouses": [
          {
            "warehouse_name": "Test Warehouse",
            "warehouse_code": "Test Code"
          }
        ],
        "buyers": [
          {
            "buyer_name": "Test Buyer",
            "buyer_email": "[email protected]"
          }
        ],
        "billing": {
          "billing_addresses": [
            {
              "billing_code": "JBNY01",
              "billing_name": "JboutiqueNY",
              "billing_phone": "0000000000",
              "billing_address_1": "1 Main St",
              "billing_address_2": "",
              "billing_city": "New York",
              "billing_state": "NY",
              "billing_postal_code": "10005",
              "billing_country": "United States"
            },
            {
              "billing_code": "JBNY02",
              "billing_name": "JboutiqueNY",
              "billing_phone": "212-555-1212",
              "billing_address_1": "1 Main St",
              "billing_address_2": "Accts Payable",
              "billing_city": "New York",
              "billing_state": "NY",
              "billing_postal_code": "10005",
              "billing_country": "United States"
            }
          ],
          "payment_methods": [
            {
              "payment_method_name": "Net 30 (Pending Approval)",
              "payment_method_code": "net30"
            },
            {
              "payment_method_name": "X30W (Pending Approval)",
              "payment_method_code": "x30w"
            },
            {
              "payment_method_name": "Other",
              "payment_method_code": "oth"
            },
            {
              "payment_method_name": "30 Days PDC",
              "payment_method_code": "30pdc"
            },
            {
              "payment_method_name": "Payment Plan",
              "payment_method_code": "pp"
            }
          ]
        },
        "shipping": {
          "shipping_addresses": [
            {
              "shipping_code": "JBNY1",
              "shipping_name": "JboutiqueNY",
              "shipping_phone": "212-555-1212",
              "shipping_email": "[email protected]",
              "shipping_address_1": "1 Main St",
              "shipping_address_2": "",
              "shipping_city": "New York",
              "shipping_state": "NY",
              "shipping_postal_code": "10005",
              "shipping_country": "United States",
              "shipping_create_doors": true
            },
            {
              "shipping_code": "JBNY2",
              "shipping_name": "JboutiqueNY",
              "shipping_phone": "212-555-1212",
              "shipping_email": "[email protected]",
              "shipping_address_1": "1 Main St",
              "shipping_address_2": "",
              "shipping_city": "New York",
              "shipping_state": "NY",
              "shipping_postal_code": "10005",
              "shipping_country": "United States",
              "shipping_create_doors": false
            }
          ],
          "shipping_methods": [
            {
              "shipping_method_name": "UPS Ground",
              "shipping_method_code": "ups_ground"
            },
            {
              "shipping_method_name": "FedEx International Economy",
              "shipping_method_code": "fedex_economy"
            }
          ]
        },
        "price_types": [
          {
            "price_type_label": "Europe",
            "price_type_currency_code": "EUR",
            "price_type_retail_currency_code": "EUR"
          },
          {
            "price_type_label": "Australia",
            "price_type_currency_code": "AUD",
            "price_type_retail_currency_code": "USD"
          }
        ],
        "customer_locations": [
          {
            "location_address_id": 25965,
            "location_address_1": "1 Main St",
            "location_address_2": "",
            "location_city": "New York",
            "location_state": "NY",
            "location_zip": "10005",
            "location_country": "United States",
            "location_phone": "212-555-1212"
          }
        ],
        "discounts": [
          {
            "amount": 4,
            "line_item_level": true
          }
        ]
      },
      {
        ...
      }
    ]
  }
}

Response Example

<?xml version="1.0" encoding="UTF-8"?>
<bulk_connections>
    <response>
        <code>0</code>
    </response>
    <bulk_connections_jobs>
        <bulk_connection_job>
            <bulk_connections_job_id>4</bulk_connections_job_id>
            <status>queued</status>
            <created>2016-07-15T19:49:19+00:00</created>
            <modified>2016-07-15T19:49:19+00:00</modified>
            <connection_record_count>142</connection_record_count>
            <connection_record_progress>0</connection_record_progress>
        </bulk_connection_job>
    </bulk_connections_jobs>
</bulk_connections>
{
  "bulk_connections": {
    "response": {
      "code": 0
    },
    "bulk_connections_jobs": [
      {
        "bulk_connections_job_id": 4,
        "status": "queued",
        "created": "2016-07-15T19:35:36+00:00",
        "modified": "2016-07-15T19:35:36+00:00",
        "connection_record_count": 142,
        "connection_record_progress": 0
      }
    ]
  }
}