curl
csharp
java
javascript
php
python
ruby
typescript

bulk

/bulk

List bulk jobs for the calling merchant

Permissions:
  • bulk_write

Produces: application/json
get
/bulk/{object}

SDK Function Name: bulkListJobs

Parameters
Parameter Description Location Data Type Required
object Object type
Allowed Values
  • order
  • customer
 path string required
status Filter by job status query string optional
cursor Opaque pagination cursor query string optional
limit Page size (default 100, max 1000) query integer (int32) optional
Responses
Status Code Reason Response Model
200
 Successful response BulkJobsResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Submit a bulk job

Permissions:
  • bulk_write

Consumes: application/json
Produces: application/json
post
/bulk/{object}

Submits a job referencing a previously uploaded NDJSON object. One active job per merchant; additional submissions queue. The bulk surface is write-only (insert / upsert); it has no bulk read or export operation.

SDK Function Name: bulkSubmitJob

Parameters
Parameter Description Location Data Type Required
object Object type
Allowed Values
  • order
  • customer
 path string required
bulk_job Bulk job submission body BulkJobRequest required
Responses
Status Code Reason Response Model
200
 Successful response BulkJobResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Generate a presigned upload URL for a bulk payload

Permissions:
  • bulk_write

Produces: application/json
post
/bulk/{object}/upload-url

Returns a presigned S3 PUT URL the merchant uploads NDJSON to, plus the s3_key to pass to submit.

SDK Function Name: bulkGenerateUploadUrl

Parameters
Parameter Description Location Data Type Required
object Object type
Allowed Values
  • order
  • customer
 path string required
Responses
Status Code Reason Response Model
200
 Successful response BulkUploadUrlResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Request cancellation of a bulk job

Permissions:
  • bulk_write

Produces: application/json
delete
/bulk/{object}/{job_id}

Queued jobs cancel immediately (200). In-progress jobs finalize as cancelled between records (202); already-processed records stand.

SDK Function Name: bulkCancelJob

Parameters
Parameter Description Location Data Type Required
object Object type
Allowed Values
  • order
  • customer
 path string required
job_id The bulk job id path string required
Responses
Status Code Reason Response Model
200
 Cancellation applied - a queued job is cancelled immediately
202
 Cancellation accepted - an in-progress job finalizes as cancelled between records
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Retrieve a bulk job's status and counts

Permissions:
  • bulk_write

Produces: application/json
get
/bulk/{object}/{job_id}

SDK Function Name: bulkGetJob

Parameters
Parameter Description Location Data Type Required
object Object type
Allowed Values
  • order
  • customer
 path string required
job_id The bulk job id path string required
Responses
Status Code Reason Response Model
200
 Successful response BulkJobResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Paginate a bulk job's per-record results

Permissions:
  • bulk_write

Produces: application/json
get
/bulk/{object}/{job_id}/records

SDK Function Name: bulkGetJobRecords

Parameters
Parameter Description Location Data Type Required
object Object type
Allowed Values
  • order
  • customer
 path string required
job_id The bulk job id path string required
status Filter by per-record result status (success, failed, duplicate) query string optional
cursor Opaque pagination cursor query string optional
limit Page size (default 100, max 1000) query integer (int32) optional
Responses
Status Code Reason Response Model
200
 Successful response BulkRecordsResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

BulkJob

Attributes
Name Data Type Description
completed_at (read only) string (dateTime) When the job reached a terminal status
duplicate_count (read only) integer (int32) Records short-circuited as duplicates
error_code (read only) string Job-level failure code when status is failed
fail_count (read only) integer (int32) Records that failed
job_id (read only) string Public-facing job id (uc-bulk-)
object (read only) string Object type this job processes
Allowed Values
  • order
  • customer
operation (read only) string Mutation mode this job runs (the bulk surface is write-only)
Allowed Values
  • insert
  • upsert
processed_records (read only) integer (int32) Records processed so far
queue_position (read only) integer (int32) Position behind the merchant's active job (queued jobs only)
results_summary_url (read only) string Presigned S3 URL to the full per-record results NDJSON (set when finished)
started_at (read only) string (dateTime) When the worker started the job
status (read only) string Job status
Allowed Values
  • queued
  • in_progress
  • succeeded
  • partial_success
  • failed
  • cancelled
submitted_at (read only) string (dateTime) When the job was submitted
success_count (read only) integer (int32) Records that landed
total_records (read only) integer (int32) Total records counted on the first pass (null until counted)

BulkJobRequest

Attributes
Name Data Type Description
operation string Mutation mode - insert (create only) or upsert (create or update). Defaults to insert. This is always a mutation verb — the bulk surface writes only and has no read / query mode. upsert is currently supported for customer only.
Allowed Values
  • insert
  • upsert
s3_key string The s3_key returned by the upload-url endpoint
webhook_secret string Optional shared secret echoed in the completion POST's Authorization header
webhook_url string Optional URL to POST once, on completion

BulkJobResponse

Attributes
Name Data Type Description
bulk_job BulkJob Bulk job
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

BulkJobsResponse

Attributes
Name Data Type Description
bulk_jobs array of BulkJob Bulk jobs
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
next_cursor (read only) string Opaque cursor for the next page, null when exhausted
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

BulkRecord

Attributes
Name Data Type Description
action (read only) string On an upsert success, whether the record was inserted or updated
Allowed Values
  • inserted
  • updated
error_code (read only) string Error code on a failed record
error_message (read only) string Human-readable detail on a failed record
line_number (read only) integer (int64) Original NDJSON line number
merchant_record_id (read only) string The merchant-supplied dedupe key for this record
status (read only) string Per-record verdict
Allowed Values
  • success
  • failed
  • duplicate
uc_id (read only) string UltraCart-side id created on success or matched on duplicate

BulkRecordsResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
next_cursor (read only) string Opaque cursor for the next page, null when exhausted
records array of BulkRecord Per-record results
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

BulkUploadUrlResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
expires_at (read only) string (dateTime) When the presigned URL expires
max_records (read only) integer (int32) Per-job record cap
metadata ResponseMetadata Meta-data about the response such as payload or paging information
s3_key (read only) string Opaque reference to pass back on POST /rest/v2/bulk/{object}
success boolean Indicates if API call was successful
upload_url (read only) string Presigned S3 PUT URL (short-lived)
warning Warning Warning object if a non-fatal issue or side-effect occurs

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
object_id string Object id that the error is associated with
user_message string An end-user friendly message suitable for display to the customer

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

ResponseMetadata

Attributes
Name Data Type Description
payload_name string Payload name
result_set ResultSet Result set

ResultSet

Attributes
Name Data Type Description
count integer (int32) Number of results in this set
limit integer (int32) Maximum number of results that can be returned in a set
more boolean True if there are more results to query
next_offset integer (int32) The next offset that you should query to retrieve more results
offset integer (int32) Offset of this result set (zero based)
total_records integer (int32) The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true.

Warning

Attributes
Name Data Type Description
more_info string Additional information often a link to additional documentation
warning_code string A stable machine-readable code identifying the warning. See API docs for known values.
warning_message string A technical message meant to be read by a developer

400
Status Code 400: bad request input such as invalid json

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

401
Status Code 401: invalid credentials supplied

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

410
Status Code 410: Your authorized application has been disabled by UltraCart

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

429
Status Code 429: you have exceeded the allowed API call rate limit for your application.

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

500
Status Code 500: any server side error. the body will contain a generic server error message

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse