TrepStar.com HTTP Gateway API order automation documentation

TrepStar HTTP Gateway API:

The TrepStar HTTP gateway API responds to http get/post requests initiated by your software/process. This is sometimes called a webhook. Currently, this API has two functions:

1. SubmitProductOrder
2. getOrderStatusByInvoice

Function - SubmitProductOrder:

Summary:

The following section explains how to submit a product order for one or more products in any quantity.

Your software will initiate an http get or post request to a TrepStar HTTP Gateway URL (https://www.trepstar.com/custdata.asp). The response from the request will include either the text [SUCCESS] or [FAILURE].

ASP Sample: Code Sample Written in classic ASP (active server pages).
PHP Sample: Code Sample Written in PHP.
Python Sample: Code Sample Written in Python.

In the sections below, we define each field, and give you an example. We show you the correct URL format you would use to call our http gateway from some server to server process on your site or shopping cart (when your system is taking or processing order information). Many shopping cards can be configured to set up a http get/post call when an order is processed. If not, you can program (or hire someone) to program the http gateway call to our server.

The TrepStar HTTP Gateway URL for 'SubmitProductOrder' starts with https://www.trepstar.com/custdata.asp

Request Format - Field Definitions:

1. productid This product id is specific to each project you have in your TrepStar.com account. The product (or project) ID is listed next to the title of each of your products. The exact TrepStar product ID is required to identify the project.
   
   Single Order (single address), but with multiple products: There may be cases when you want to order multiple products to be shipped in the same box/package to the same address. For example: Suppose you wanted to order 3 different products each with a different quantity. First, string productid's together separating them with an x.
   1. E.g. Customer Order with 3 products A, B, and C with TrepStar IDs 66750 and 66760 and 66770 respectively. The productid field would look like productid=66750x66760x66770.
   2. To specify quantity for each product, see the 'quantity' field below. (e.g. quantity=1x3x2)
   3. This multi product order will cause our server to manufacture, print and package these three products together in one box/package (in the quantity specified by the quantity field below).
      
      
2. quantity Use a numeric value from 1 to 250. 1 is the default value. If you leave quantity blank or don't include it, 1 will be assumed. Quantity refers to how many of 'productid' product(s) will be shipped to the end user. If you need more than 250, submit two separate orders.
   
   Single Order (single address), but with multiple products: There may be cases when you want to order multiple products to be shipped in the same box/package to the same address. For example:
   1. You can specify a different quantity for multi-project orders. For example, if you have the productid=40350x40360x40370, you could set quantity=1x4x3
   2. This means we will make 1 of project 40350, 4 of project 40360, and 3 of project 40370, and they will all ship in the same box/package to the same address.
   3. quantity is positional. The first productid in the productid list will correspond to the first quantity in the quantity list.
      
      
3. Invoice
   1. Invoice can be text up to 50 characters.
   2. If you plan to get order status via the API method getOrderStatusByInvoice you must include a unique invoice for ALL of your orders.
   3. You may leave Invoice blank but we highly discourage it. If it's blank then we use the 'email' field below instead. Email is the next best unique identifier for an order. The order will fail [FAILURE] and be considered a duplicate if the same email address is used on an order within 5 days (when no invoice was used). In other words, the same user (same email) can order this product again, but only after 5 days.
   4. Invoice is important because we want to make sure we are not accepting duplicate orders (and billing your for them). For example, if your system submitted 5 orders, each without invoice or email, we assume they are different orders since the software does not compare every single field for a match. We are trying to avoid submitting multiple duplicate orders sent to the same customer in the case where your system retries an order or is in an error loop. Therefore, if you supply a unique invoice, our system will correctly reject duplicate order requests if the same invoice is used. This is the primary reason why it's critical to have a unique invoice.
   5. Invoice must be unique for this productID. In other words, you can use the same invoice value again for a different product/project, but not for this project. However, we highly recommend you create a unique invoice for ALL of your orders, not just on a project by project basis, especially if you think you may use the getOrderStatusByInvoice function.
      
      
4. typeMailMethod Values are standard, rtrackstandard, priority or express. rtrackstandard means standard + tracking.
   1. If your product is packaged in a sleeve or usb ecomailer, and it's a single quantity order, standard is the lower cost letter rate with no tracking.
   2. If your product is packaged in anything else, or it's to an INTL address, it's shipped as a parcel which includes tracking to most destinations and in these cases, is almost exactly like rtrackstandard. If you specified standard, but a package needs to be sent as a parcel, the order will still be accepted (will behave as if it was ordered using rtrackstandard).
   3. Priority is 2-3 days shipping time (plus 1 day production time). We try to get priority and express packages out as fast as possible. For a domestic address, Priority packages usually arrive 2-3 business days after the order has been paid and postage printed. Add a few more days for INTL addresses.
   4. Express is 1-2 days shipping time (plus 1 day production time). We try to get priority and express packages out as fast as possible. For a domestic address, Express packages almost always arrive 2 business days after the order has been paid and postage printed. Use this choice if you need to guarantee Amazon 2 day delivery for Prime members (domestic addresses only). Add a few more days for INTL addresses.
   5. For more information, open the order form for one of your products and read the help text in the shipping policy section near the bottom of the form.
   If you do not specify the typeMailMethod, the setting within your account will be used. Login, click the account button, and find the 'Default Order Mail Method' setting to set the default value. Click here for more information about shipping method and tracking.
   
   
5. CoLoginEmail This is your TrepStar publisher account email (used to login to your TrepStar.com account). At this time, we don't have a separate API key or password so if you change your email or password, be sure to update your order automation software.
   
   
6. CoLoginPassword This is your TrepStar publisher account password.
   
   
7. mode Values are either test or prod. (e.g. mode=test)
   1. test mode orders will be accepted and will show up in the TrepStar dashboard (click the recent orders button). Use test mode when first testing this integration. You will receive the customer order notification email if you have that feature on. Test orders cannot be converted to prod orders. Test orders may be deleted from the dashboard.
   2. prod mode orders are live orders that will be billed to your account, and manufactured & shipped when they are paid for. Normally, your account does not have a positive balance when you are a new publisher. In other words, prod orders will be on hold unless you have a positive TrepStar account balance (a credit from a previous payment). 'hold' orders are not yet manufactured, so you may delete them from the dashboard (e.g. the recent orders list).
   
   
   
8. email Customer's Email. Normally it would be the email address of your customer so they may receive our optional order notification and/or tracking information of you have that feature on.
   1. Email is used if you have Customer Email Notifications turned on within your publisher account settings (ON by default).
   2. Email is used only to send order related emails.
      1. This includes the order notification which contains an optional address modification link.
      2. A separate tracking link email is sent later, when postage is printed and a tracking number becomes available.
   3. Customer Email Notifications can be turned on/off by editing your TrepStar account settings.
   4. Customer Email Notifications are important if you want your customer to be able to modify his address in case they see errors. We send the order notification right away when the order is placed, which gives them time to modify their address before we actually print postage. The amount of time for this postage printing delay, and the use of the modify address setting can be found within your TrepStar Account settings.
   5. If you want email sent to customers in only certain cases, leave the notifications setting on, but for those customers where you don't want email sent, use one of your internal emails, or create a 'fake' email (e.g. internal@yourco.com or bogus@hotmail123.com). Or, look at the bSendOrderNotificationEmail section below.
      
      
9. bSendOrderNotificationEmail (1 or 0) Optional: Send Order Notification Email to customer or not. This setting will override the Customer Email Notifications setting within your TrepStar Publisher Account. If you set bSendOrderNotificationEmail=1 we will send the Order Notification Email (and tracking email) to the email supplied on this order regardless of the TrepStar account setting. Setting bSendOrderNotificationEmail=0 means no emails will be sent even if you have the TrepStar Publisher Account setting set to Yes.
   
   
10. nprice Optional. If you want an amount printed on the invoice we include with the package, set this value to a dollar amount. This goes on the printed invoice inside the package (e.g. You've already paid $xx.yy for this order...) If you use 0 (zero) for the price, the amount will not be mentioned in any customer receipt email notification, and will not be printed on the customer invoice.
    
    
11. bUsePriceOnCustomsForm (1 or 0) Optional: This field has meaning for International orders only. VAT tax is determined by package value. Normally, we use $6.00. if you set bUsePriceOnCustomsForm=1 we use the price you set in the nPrice field (above). If you leave this field blank or 0, we use the $6.00 value.[more info].
    
    
12. name Customer's full name. (e.g. John H. Smith)
13. co Company name. (e.g. Capital Records or ATTN: John Smith, 3rd floor)
14. addr Full street address. (e.g 123 some street, Apt123). If the address has 2 lines, put them together (concatenate) as a single line.
15. city City
16. st State or Province. Required for USA and Canada, and countries that have a state, but some countries do not have a state value so it can be left out in those cases. Use either the 2 letter state abbreviation or spell it out fully. (e.g. MN or Minnesota is acceptable separately but do not combine them twice. (e.g. MN Minnesota) is NOT acceptable).
17. zip Zip Code, or postal code for international addresses.
18. country Country.
    1. If blank, US (United States) is assumed and is the default value.
    2. If possible, use the standard 2 letter country code values like 'US' for United States, or 'UK' for united kingdom if possible (Google "2 letter country codes").
    3. You may also fully spell out country names. (e.g. UniTed KINGdom, or Great Britain).
    4. Our system is fairly well trained when accepting country names, and even common misspellings are handled most of the time. 'IT' or 'Italy' is acceptable, but do not combine too much data. (e.g. IT (Italy) will fail).
    5. If there are errors with the address, we normally catch this when printing postage later. The order submit status will be [SUCCESS] even if we have to correct the address manually. We don't do address verification on this order submit step. You will need to use the getOrderStatusByInvoice method to check status and get tracking codes.
    6. For bad addresses we may send an email to the customer using the email (field above) used when placing this order. We will ask the customer for corrections (since the end user customer knows best what their address is). If we can not contact them we send an email to your publisher email for clarification. See the send status list.
       
       
19. SpecialText Use this information to give this customer specific instructions valid only for him/her such as a serial#, unlock code etc. If you specify any special text, it overrides the special text that you specified from within the project settings. Maximum 500 characters. No HTML.
    
    
20. ordermethod=url (Value is always set equal to url). (e.g. ordermethod=url) This value never changes so always set as ordermethod=url . This tells us this is an http gateway call instead of an order from a different method such as a 3rd party shopping cart.
    
    
21. source=cdfulfill (Value always set equal to cdfulfill). Use cdfulfill even if this is a DVD or USB order. (e.g. source=cdfulfill) This value never changes so always set source=cdfulfill . This tells us this is an http gateway call instead of an order from a different source such as our retail order buttons.
    
    

Server Response:

1. [SUCCESS] The http gateway call to our server will return information about the order, including the word [SUCCESS] if the order was processed. There may be other summary information you can ignore in the response, but the word [SUCCESS] (case sensitive) will be displayed.
2. [FAILURE] The http gateway call to our server will return information about the order, including the word [FAILURE] if the order was NOT processed. Duplicate orders are not processed and will be considered [FAILURE]. Duplicate orders are orders with the same invoice value. You are not allowed to order the same product with a previously used invoice. There may be other failure error messages. For example, if there is no customer name or address, an error message will be generated.
3. The format of a failure will include an error code and error message in the following format:
   [ERRORMSGBEGIN] ERRCODE#nnnnnn [FAILURE] Error Message Here [ERRORMSGEND]
   
   Your process can scan the server response for the keyword [FAILURE] and/or parse out the area between [ERRORMSGBEGIN] and [ERRORMSGEND]. The ERRCODE always directly follows [ERRORMSGBEGIN], and the error message always follows the keyword [FAILURE].

Failure ERRCODEs and FAILURE messages:

1. ERRCODE#000503 [FAILURE] http gateway URL Integration Call is Invalid. Source Mode Unknown. You must include your account email and password which must match your login to www.TrepStar.com. The field names you must add are CoLoginEmail and CoLoginPassword. Refer to http://www.trepstar.com/automate-integrate-ordering.asp
2. ERRCODE#000101 [FAILURE] prod, productid, and eCommerceList were blank. For integration customers, you need to specify only the productid field. This should be the numeric value of your TrepStar project id (login and look for it)
3. ERRCODE#003101 [FAILURE] The total quantity for this multi product order exceeded the maximum 250. The quantities you submitted were xxx which total yyy.Please click back, enter smaller quantities, or submit separate orders. The post office limits us to a total size and weight per package.
4. ERRCODE#000601 [FAILURE] Your URL (http gateway) Integration Call does not have the correct CoLoginEmail and CoLoginPassword. You must provide your current www.trepstar.com login email and password on the http gateway URL integration call. CoLoginEmail and CoLoginPassword are the field names you must use. Either you have not specified them, or they are incorrect. Please refer to http://www.trepstar.com/automate-integrate-ordering.asp for more details.
5. ERRCODE#000505 [FAILURE] Your http gateway URL Integration Call has the correct CoLoginEmail and CoLoginPassword, but the product you are trying to make (xxxyyy) is not from this account CompanyID='yyy' ParentID of Product='aaabbb'. You can only order for products within your account using this email and password .
6. ERRCODE#000503 [FAILURE] http gateway URL Integration Call is Invalid. Source Mode Unknown. You must include your account email and password which must match your login to www.TrepStar.com. The field names you must add are CoLoginEmail and CoLoginPassword. Refer to http://www.trepstar.com/automate-integrate-ordering.asp
7. ERRCODE#000002 [FAILURE] Invalid access or source variable value. If you are attempting to send data for TrepStar CD/DVD/USB fulfillment service, your GET or POST variables are malformed or you did not specify the right value for 'source' which should be cdfulfill. The value of source supplied by you was 'xxxx' .The List(s) at the top of this page shows the only readable form or querystring variables, we received, if any.
8. ERRCODE#000010 [FAILURE] ProductID was blank
9. ERRCODE#000013 [FAILURE] Name was blank
10. ERRCODE#000035 [FAILURE] This is a duplicate Order. This order, taken by our server at [date/time] will not be filled because [some reason] Please login to your trepstar.com account, and click the 'reports' button to see the recent list of orders. If you do not see your customer listed, the order did not go through. To prevent our system from thinking an order is a duplicate, use a unique email or unique invoice# to prevent duplicate orders.

GET/POST Parameters:

1. URL Encoding: Be sure to use proper URL encoding when sending text data. For example, the text "Thank you for ordering. Your unlock code is 123-23456. Email questions to help@somedomain.com" needs to be URL encoded. This text properly URL encoded would be sent to the server looking like "Thank+you+for+ordering%2E++Your+unlock+code+is+123%2D23456%2E++Email+questions+to+help%40somedomain%2Ecom".

WebHook to TrepStar:

Your software or server will call our server (sometimes known as a webhook) with specific customer data. Use your TrepStar productID number(s), and your TrepStar login email and password.

Each TrepStar product has a unique productID assigned by our system. The following is just an example. When you create your own project, you will use the unique Product id assigned by our system used to identify your specific product.

Single Product Order Example. Webhook parameters to our server:
Example webhook URL to produce a single product order with quantity=1.

https://www.trepstar.com/custdata.asp?productID=139610&quantity=1&ordermethod=url&invoice=234ABC&typeMailMethod=standard&CoLoginEmail=trepstarloginemail@somehwere.com&CoLoginPassword=YourTrepStarPassword&source=cdfulfill&mode=test&email=&name=Jon+Doe&nprice=12&bUsePriceOnCustomsForm=0&co=Customer+CompanyName&addr=35234+Maple+Street+STE+300&city=Inver+Grove+Heights&st=MN&zip=55077&country=US&specialtext=Thank+you+for+your+order%2E++Your+Reg+Code+is+3452%2D3432%2D3563

Multiple Product Order Example (with different quantities for each product).
In this example, there is a list of TrepStar productIDs and Quantities. The first product will have a quantity ordered of 4, 2nd product qty=2, and 3rd product qty=2.

https://www.trepstar.com/custdata.asp?productID=139610x12345x54321&quantity=4x1x2&ordermethod=url&invoice=1234ABCD&typeMailMethod=priority&CoLoginEmail=trepstarloginemail@somehwere.com&CoLoginPassword=YourTrepStarPassword&source=cdfulfill&mode=test&email=&name=Jon+Doe&nprice=12&bUsePriceOnCustomsForm=0&co=Customer+CompanyName&addr=35234+Some+Street+APT#3&city=Inver+Grove+Heights&st=MN&zip=55077&country=US&specialtext=Thank+you+for+your+order%2E++Your+Reg+Code+is+1233%2D3452%2D3432

Function - getOrderStatusByInvoice:

Summary:

The following section describes how to retrieve order status from a previously submitted order.

For the GetOrderStatusByInvoice function, your software will initiate an http get or post request (a webhook) to a TrepStar HTTP Gateway URL (https://www.trepstar.com/custdataXML.asp). The response will be in XML format.

The getOrderStatusByInvoice function will retrieve the status of a previously placed order. The response will contain delivery status, and a shipping tracking id if applicable. Each http call to the service results in a single XML response. Please do not abuse this service by calling our server too often. If you call this function over 1000 times in a 24 hour period, we charge 1 cent ($0.01) each time the function is called (we will bill your TrepStar account). Be careful to avoid frequent looping calls (or infinite loops). Any abuse of this service will be considered a denial of service attack and may result in us having to block your system and/or close your TrepStar account.

Input: Invoice you used when creating the order (the invoice you specified when ordering).

output: XML Response

Request Format:

Formulate an http get or post request to our server at this url https://www.trepstar.com/custdataXML.asp using 4 fields.

1. function - Set to 'getOrderStatusByInvoice'.
2. Invoice - Use the unique invoice (or list of invoices *) you supplied when you submitted the order. If you plan to use this XML response feature, you must make sure you supply a unique invoice when you submit the order.
   1. * You may also specify multiple (up to 100) Invoice values on a single request to get the status of multiple orders.
      1. String several Invoice values together with this delimiter [*|*]
      2. The limit is 100 invoices. Only the first 100 invoices in the list will be checked.
      3. This 5 character delimiter is necessary because invoices are allowed to be any combination of English text or numbers so the delimiter must be unique.
      4. e.g. Invoice=ABC2134234[*|*]DEF592839234[*|*]SDF234234234 would return 3 status sections with information about all three of these invoices.
3. CoLoginEmail - This is the email address you use to login to your TrepStar.com account. We use this for security reasons.
4. CoLoginPassword - This is your account password used for security reasons.

URL Encoding

1. Be sure to use proper URL encoding when sending text data. For example, if the invoice was "ID 000052 5/16/18", it would need to be URL encoded. This text properly URL encoded would be sent to the server looking like "ID+000052+5%2F16%2F18".

Here is what a sample getOrderStatusByInvoice request URL looks like using a single Invoice as input:

https://www.trepstar.com/custdataXML.asp?function=getOrderStatusByInvoice&Invoice=ID+000052+5%2F16%2F18&CoLoginEmail=joesmith%40someco%2Ecom&CoLoginPassword=234xyz

XML Response Example:

The response from the system will be in XML format.

<Status1> <ErrorNum>0</ErrorNum> <ErrorDesc></ErrorDesc> <CustName>John Smith</CustName> <Invoice>ABC12312321</Invoice> <OrderStatus>Processing</OrderStatus> <OrderStatusErrNum>0</OrderStatusErrNum> <OrderStatusErrDesc></OrderStatusErrDesc> <ShippingMethod>Standard</ShippingMethod> <ShipDate>11/21/2024</ShipDate> <TrackingID>9400111202530525069711</TrackingID> </Status1>
If your request contains multiple Invoice values, multiple Status sections will be returned.

XML Data Output Fields:

1. <StatusN> Section(s) - All of the XML field values are contained within the StatusN Section(s) of the response.
   1. If you submit a single invoice as input there will only be one section in the response.
      1. <Status1>
         ...
         </Status1>
         
   2. If you submit multiple invoice values as input, multiple sections will be in the response. The output sections are in the same positional order as the input invoice list.
      1. <Status1>
         ...
         </Status1>
         
      2. <Status2>
         ...
         </Status2>
         
      3. etc.
         
      
      
      
   3. ErrorNum
      1. 0 - success.
      2. 100 - Unknown function name requested. Please specify a valid function on the get/post request. Valid functions are:
         1. getOrderStatusByInvoice
      3. 200 - Incorrect email or password used as input.
      4. 300 - Record Not found. The input Invoice data is not in our database. If you receive this error, you were correctly authenticated. (correct login email and password), but no product order record was found with that invoice.
         
         
   4. ErrorDesc - Descriptive error text related to each error response. ErrorDesc will be blank for successful (0 ErrorNum) requests.
      
      
   5. CustName - The customer name is returned mostly for testing purposes. You may want to confirm this customer is in fact the correct customer for the supplied Invoice.
      
      
   6. Invoice - The input Invoice is returned as output in case you want to check it when you've submitted multiple invoices as input.
      
      
   7. OrderStatus - Manufacturing and fulfillment status. Possible values are:
      1. ERROR - Usually an address error. Look at OrderStatusErrNum and OrderStatusErrDesc.
      2. HOLD - A payment needs to be made before this order is manufactured and fulfilled.
      3. PROCESSING - Currently being manufactured but not yet shipped.
      4. SHIPPED - Postage has printed, and product has shipped (or will be in the mail soon). See ShipDate for expected shipping date.
         
         
   8. OrderStatusErrNum - If OrderStatus = "ERROR", OrderStatusErrNum gives you an error code:
      1. 0 - success.
      2. 10 - Error with address. See the ErrorStatusErrDesc for more detailed information.
      3. 20 - Test order. You submitted a test order which will never be manufactured or shipped. Test orders may be submitted when you test your order automation.
         
         
   9. OrderStatusErrDesc - If OrderStatus = "ERROR", OrderStatusErrDesc gives you descriptive error text information related to the error code specified in OrderStatusErrNum.
      
      
   10. ShipDate - Date the package shipped (or is expected to ship). Format mm/dd/yyyy. Once postage has printed a ShipDate is set, and sometimes this is in the future (tomorrow or next business day for example).
       
       
   11. ShippingMethod - The shipping method you requested during the order process. Possible Values:
       1. standard
       2. standard+tracking
       3. priority
       4. express
          
          
   12. TrackingID - The tracking ID (if tracking is available).
       1. Use this URL to see the tracking information: https://www.endicia.com/tracking/?pic=trackingID
       2. TrackingID will be blank if no tracking is available (such as domestic standard rate first class letters or flats).
       3. For International (INTL) shipments, tracking may only be available to the point the package leaves the USA unless you use Priority or Express shipping.