Troubleshooting

Base URL: https://v2.api.finerworks.com · Routes: /v3/<endpoint> · Body: JSON

Quick checklist

Work through these in order before opening a support request.

1. Call GET /v3/test_my_credentials. If it succeeds, your keys, account and profile are fine and the problem is in the specific call.
2. Check which mode your app is in. An app key in test mode silently turns every order into a test order (see Test mode vs live mode). This is the most common surprise.
3. Read the whole response, not just the HTTP code. Several failures return HTTP 200 with success: true and the real problem in status.message or an empty result.
4. Run submit_orders_v2 with validate_only: true before a real submit. It catches most address, shipping-code, duplicate-PO and SKU errors without creating an order.
5. Keep the reference_id from the response status block when you contact support.

If the problem persists after these checks, contact our customer service team (email only).

Reading responses

Responses come in three shapes. Your client needs to handle all of them.

• In validation errors the ModelState key is often a .NET type name such as System.Collections.Generic.List`1[ApiC.Models.order_details]. Ignore the key and read the message.
• Validation runs in stages, so you may fix one error and then see a different one. Errors appear in this order: JSON binding, credentials, account billing/business profile, duplicate PO, shipping code, product/SKU, order count.
• Validation errors have no reference_id. Only envelope responses do.
• Send Content-Type: application/json. XML and form-encoded bodies are not supported.
• JSON property names are snake_case (order_po, product_qty). Matching is case-insensitive and unknown properties are ignored, so a typo in an optional field is silently dropped rather than rejected.
• Some endpoints are GET but take a JSON body (for example test_my_credentials, get_payment_tokens, list_order_status_definitions). Many HTTP clients and proxies strip bodies on GET. The API Reference shows the method for each endpoint.
• Always call https://. Plain http:// gets a 301 redirect, and many clients drop the body and headers (or turn a POST into a GET) when following it.

Authentication & account setup

Credentials are two GUIDs, web_api_key and app_key, sent as request headers (or as query-string parameters; if both are present the query string wins). Get them from the FinerWorks account dashboard under API credentials.

test_my_credentials runs the credential check and the billing/business checks together, so it surfaces all of the problems above in one call.

Test mode vs live mode

Each app key has a live/test setting, which you change in the FinerWorks dashboard (or with PUT /v3/update_app_details).

Other things that force test mode: a payment_token of xxxx, and any test order in a batch (one test order puts the whole batch in test mode).

What test mode does:

• Orders are not approved or produced, and are hidden from list_orders.
• Account credits are not withdrawn.
• Emails are prefixed [TEST MODE].
• Payments go to the Braintree sandbox, which only accepts sandbox payment tokens.

Get payment tokens from GET /v3/get_payment_tokens (add ?sandbox=true for sandbox tokens). It returns 404 if the account has none on file for that environment.

Submitting orders (submit_orders_v2)

Run with validate_only: true first. It checks everything in this table except payment, price and image reachability.

These are not validated at submit time, so they won't fail here but may cause problems later in production: whether the image URL is reachable, its file type, its real pixel size or DPI, and the zip-code format. See Images & inventory.

Behavior to know about:

• If your shipping_code is valid but not offered for that parcel and destination, the order is priced with the first available rate instead of being rejected.
• An invalid or zero-discount promo_code is ignored rather than rejected.
• customs_tax_info is optional and is not enforced for international orders.

Payments

On success, a "FINERWORKS FULFILLMENT SUBMITTED - SUCCESS" email is sent to the account email.

After you submit: status, changes, webhooks

Response on success: orders[] with order_id, order_po, order_guid and order_status{order_status_id, order_status_label}, plus the message Orders have been successfully submitted.

Checking status: POST /v3/fetch_order_status with order_ids or order_pos.

• It always returns HTTP 200. An unknown id comes back as order_status_id: 0 with the label Order ID Incorrect or Not Found.
• Lookup by PO returns at most the 5 most recent matches, and is ignored if order_ids is also sent.
• GET /v3/list_order_status_definitions lists the status names.

list_orders hides test orders, unapproved orders, and cancelled orders (unless show_cancelled is true). get_order requires both order_guid and order_email, and the email must match the order's billing email; otherwise it returns 404.

Cancel / hold / resume: PUT /v3/update_order with an update_command of pending, hold or cancel. It only works while the order's current status allows it; otherwise you'll get 403 Due to where this order is within our processing, you will need to contact customer service to request any change to this order. Treat cancel as a request: it notifies customer care and isn't guaranteed.

Webhooks: you can supply webhook_order_status_url (alias webhook_url) on an order. FinerWorks stores it with the order and handles delivery.

Images & inventory

The API does not download or inspect your image when you submit. product_image.product_url_file and pixel_width/pixel_height are stored exactly as sent. Reachability, file type, size and resolution are checked later in production, so a bad image does not fail at submit time.

To avoid problems downstream:

• Use a public, stable HTTPS URL that returns the file directly — no login, no redirect to a web page, and no URL that expires before production picks it up.
• Send accurate pixel_width and pixel_height. They drive orientation and crop, so a wrong value can rotate or crop the product unexpectedly.
• URL-encode characters such as ' in the URL. An apostrophe can silently break the order's item record.
• Crop-to-fill is the default. Send custom_data_1: "fit" on the item to avoid cropping.

list_images

sort_field accepts title, file_size, date_added, date_updated, file_name and (inventory only) rank. Anything else sorts by id. sort_direction is descending unless you send ASC.

Other image and inventory calls

• add_images is not available to external accounts (it returns 403 You do not have proper permissions to run this request). Supply images inline on the order item instead.
• update_images: returns 200 even if no GUID matched. An omitted title resets to the file name, an omitted description is cleared, assigned_gallery_subcategory_ids replaces all prior assignments, and a rank of 0 or omitted keeps the old rank.
• delete_images: a soft delete. Returns 200 even if the GUID wasn't found.
• update_virtual_inventory: overwrites every field on every call. Omitting description clears it, omitting asking_price sets it to 0, and track_inventory and quantity_in_stock default to false and 0. Always send the full record. The 400 Must be an array of the correct object type and count. means 0 or more than 50 entries. SKUs that don't belong to your account are skipped without an error.
• list_virtual_inventory: an apostrophe in product_code_filter, or more than 50 codes, gives an empty result. More than 50 sku_filter entries are ignored.

Products, SKUs & pricing

• get_prices / validate_product limits: 1–50 products per call. Outside that range, get_prices returns Must be an array of the correct object type. (the message doesn't mention the limit). validate_product processes only the first 50 and drops failures silently.
• get_prices total: total_price is the sum of product, color correction, frame, glazing and mats for one unit. Quantity is not multiplied in — multiply it yourself.
• validate_product is structural only. It confirms the code is well formed, not that the materials exist, are active, or fit together. Messages: Product appears to be valid., The product_sku appears to be invalid, The product_code appears to be incorrectly formatted.
• SKU format: codes are case-insensitive; a trailing C means color correction; DD means a decimal point; AP<acct>P<id> is a virtual-inventory SKU (any "AP" inside a SKU makes it be treated that way). Use build_product_code rather than hand-building codes.
• Image vs product shape: orientation comes from the pixel_width/pixel_height you send. For rotatable products an 8X10 SKU with a landscape image becomes 10X8.
• frame_builder: errors arrive as validation messages: The width or height is outside of this framing choice's min/max size., Glazing cannot be used with this type of framing option., Matting cannot be used with this type of framing option., and Width and/or height must be provided. Mat-window problems are not reported. The glazing min/max values returned by list_glazing are generic values, not per-frame limits.
• list_product_types returns a bare array (no status wrapper) and only "create-a-print" types, so frames are not listed. list_media_types needs a request body that includes site_id.
• update_user: requires account_key (otherwise 403 Account cannot be updated. Please check the account_key.). Two social_links keys that map to the same field cause a 500. A logo_url that can't be downloaded is skipped and the call still returns 200.
• Promo codes: find_promo_code and apply_promo_code are not available to external accounts (400 with an empty error body).

Limits and platform behavior

Still having issues? Contact support

To help us resolve it quickly, include the following:

• The status.reference_id from the response (if there is one), and the time of the call with its time zone.
• The endpoint, the HTTP method, and the request body with payment tokens and keys removed.
• The full response body.
• Your account username, which app you called from, and whether that app is live or in test mode.
• For order problems: the order_po and order_id.