Skip to content
YoPrintDevelopers

Change a job number

Open .md

PUT/v2/api/store/{team_slug}/v2/job/{hash_id}/scoped_id

v2Operation ID v2_public_job_update_scoped_id

Sets the job number (scoped_id, shown as JOB-<number>). Returns the updated job.

The value is saved as sent: it isn't validated or checked for duplicates, so check your numbering before you call.

Permission

Needs permission to edit the job's sales order:

  • the team owner;
  • a role whose Manage Sales Orders permission is "update all";
  • a role with "update assigned" when you created the order or are assigned to it; or
  • on a draft order, its creator when their role can create sales orders.

Otherwise 403 user_is_not_authorized.

Business rules

  • The JOB- prefix is added when the number is shown; send the bare number.

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • hash_idstringrequired

    The job's hash id (id). Hash ids only: a unique key or a document number gives 404.

    • Example WaGvtaWsx7Kcn4

Query parameters

  • omit_media_approval_itemsstring

    Optional. 1 (or true, yes, on) makes the answer smaller: each mockup and production file's current_approval leaves out its items list, and every other key stays as it is. The job's pending_approval and webhook payloads keep their items. Every file repeats its approval with all of its items, so a job with many files on one approval answers with far less data this way; read approval items from the approvals operations instead. Left out (or any other value), the answer is unchanged. Only the query string is read: a body field with this name is ignored.

    • Example 1

Request body

application/json, required.

  • scoped_idstring

    The new job number, without the JOB- prefix. Always send it: leaving it out clears the number.

Response

200Successful response.

  • dataobjectrequired

    A job.

    Child fields (43)
    • approval_ready_mockup_design_countinteger
    • assigned_usersarray of objects

      People on the job.

      Fields of each item (3)
    • auto_saved_forstring | null

      Set only on autosave copies.

    • customerobject
      Child fields (2)
      • idstring | null

        The customer.

      • namestring | null
    • due_datestring (date-time) | null

      Production due date. ISO 8601 with offset, or null.

    • from_legacyboolean
    • has_serviceboolean

      Kept for older clients; not a count of services.

    • idstring

      The job.

    • impression_countnumber | null
    • inventory_statusstring | null

      The stock status of the job's lines.

    • is_rushboolean
    • item_countnumber | null

      Units on the job.

    • location_countnumber | null
    • mockuparray of objects

      Mockup files.

      Fields of each item (3)
      • idstring

        The file.

      • namestring | null
      • urlstring | null

        Download link with its own access token.

    • mockup_design_countinteger
    • mockup_summaryobject
      Child fields (2)
    • namestring | null
    • need_cust_provide_productboolean | integer | null

      Blanks are provided by the customer.

    • notestring | null
    • order_customer_po_numberstring | null
    • order_idstring

      The order.

    • order_scoped_idstring

      The order number.

    • pdfarray of objects

      PDF links.

      Fields of each item (2)
      • labelstring
      • urlstring (uri)

        A download link that carries its own long-lived access token: don't publish it.

    • pending_approvalany

      The open approval request, if any.

    • pipelinesarray of objects

      The job's tasks.

      Fields of each item (24)
      • assigned_usersarray of objects

        Who is assigned.

      • created_atstring (date-time)
      • due_datestring (date-time) | null

        Task due date. ISO 8601 with offset, or null.

      • idstring

        The task.

      • job_idstring

        The job.

      • job_is_rushboolean | integer | null
      • job_item_countnumber | null
      • job_namestring | null
      • job_scoped_idstring

        The job number with its prefix.

      • job_status_idstring | null

        The job's current status.

      • namestring
      • notestring | null
      • order_idstring

        The order.

      • order_namestring | null
      • order_scoped_idstring | null

        The order number.

      • pipeline_idstring

        The task preset it comes from.

      • positioninteger

        Order among tasks; lower comes first. 0 when unset.

      • sales_orderobject

        A summary of the job's order.

        Child fields (14)
      • start_datestring (date-time) | null

        Task start. ISO 8601 with offset, or null.

      • statusobject

        A status: label, kind and place in the list.

        Child fields (9)
        • colorstring | null

          Hex color.

        • customer_labelstring
        • idstring

          The status.

        • labelstring
        • pipeline_idstring

          Only on the statuses of a task preset (role pipeline): the task preset. Absent on other statuses.

        • positioninteger

          Its place in the team's list: sort by it to find the next status.

        • rolestring

          Which list it belongs to: job for job statuses, pipeline for the statuses of a task preset.

          • One of: "order", "quote", "job", "purchase_order", "shipment", "customer_message", "pipeline"
        • trashedboolean

          The status was deleted.

        • typestring

          The kind of status: start (Pending), pre_production and in_progress (In Progress), end (Completed).

          • One of: "start", "pre_production", "in_progress", "end"
      • status_completion_datestring (date-time) | null

        When it reached a Completed status. ISO 8601 with offset, or null.

      • status_idstring

        The task's status (a status of its task preset).

      • status_last_change_datestring (date-time) | null

        When the status last changed. ISO 8601 with offset, or null.

      • updated_atstring (date-time)
    • positioninteger | null
    • pricing_original_totaldecimal pair

      The job's price before pricing rules, at the stored scale. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

    • pricing_rule_appliedobject | null

      The pricing rule that set the job's decoration price, or null. These answers usually carry only type, the two ids and the two totals. List the jobs of a sales order or quote and Get one job of a sales order or quote answer with the full summary (the rule's current name and position, the prices before and after).

      Child fields (12)
      • afterstring | null

        Full summary only: the price after the rule, as a decimal string.

      • after_totaldecimal pair

        The decoration price after the rule. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

      • basestring | null

        Full summary only: the decoration price the rule started from, as a decimal string.

      • base_typestring | null

        Full summary only: service_price.

      • normal_pricestring | null

        Full summary only: the price with no rule (the same as base for a job).

      • original_totaldecimal pair

        The decoration price before the rule. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

      • pricing_group_idstring | null

        The pricing group.

      • pricing_group_namestring | null

        Full summary only: the group's name now.

      • pricing_group_removedboolean | null

        Full summary only: true when the group was removed since. The job keeps its price.

      • pricing_rule_idstring | null

        The pricing rule.

      • ruleobject | null

        Full summary only: the rule as the group holds it now (id, label, position, where 1 is the first rule checked), or null when it no longer exists.

      • typestring | null

        service on a job.

    • pricing_totaldecimal pair

      The job's price, at the stored scale (usually 6 decimal places: { "value": 600000000, "dp": 6 } is 600.00). A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

    • production_filearray of objects

      Production files.

    • qr_code_urlstring | null

      A QR code image for the job.

    • sales_orderobject

      A summary of the job's order.

      Child fields (14)
      • created_bystring | null

        Who created the order.

      • cust_due_datestring (date-time) | null

        Order customer due (in-hand) date. ISO 8601 with offset, or null.

      • due_datestring (date-time) | null

        Order production due date. ISO 8601 with offset, or null.

      • external_typestring | null

        shopify when the order came from Shopify, else null.

      • is_quoteboolean
      • is_rushboolean
      • issue_datestring (date-time) | null

        Order issue date. ISO 8601 with offset, or null.

      • namestring | null

        Order name.

      • object_typestring | null

        sales_order or quote.

      • ship_due_datestring (date-time) | null

        Order ship-by date. ISO 8601 with offset, or null.

      • shopify_deleted_externallyboolean
      • shopify_deleted_externally_atstring (date-time) | null

        When it was deleted in Shopify. ISO 8601 with offset, or null.

      • start_datestring (date-time) | null

        Order production start. ISO 8601 with offset, or null.

      • status_idstring | null

        The order status.

    • scoped_idstring

      The job number as shown, with its JOB- prefix. Change a job number takes only the digits.

    • servicesarray of objects

      The services (decorations).

      Fields of each item (9)
    • services_still_validboolean
    • start_datestring (date-time) | null

      Production start. ISO 8601 with offset, or null.

    • statusobject

      A status: label, kind and place in the list.

    • status_completion_datestring (date-time) | null

      When it reached a Completed status. ISO 8601 with offset, or null.

    • status_idstring

      The job's current status: its production stage. Look it up in List job statuses, or read status.

    • status_last_change_datestring (date-time) | null

      When the status last changed. ISO 8601 with offset, or null.

    • total_qty_need_orderingstring | null

      Quantity that still needs ordering, with 8 decimal places ("12.00000000"). A decimal string, such as "0.00000000"; parse it as a decimal.

    • unique_keystring | null

      The job's unique key.

    • versioninteger
  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

    When
    Your role can't edit this order.
    Fix
    Ask the team owner to adjust your role or assign you to the order.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    The job isn't your team's, or its order is an old (version 1) order. Jobs on quotes work too.
    Fix
    Check the job id.

Notes

  • Leaving scoped_id out clears the number. Always send it.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com