1. REST API for Oracle Fusion Cloud ProcurementREST API for Oracle Fusion Cloud Procurement
  2. Use Cases
  3. Update Blanket Purchase Agreements

Update Blanket Purchase Agreements

You can use the Purchase Agreement Import Requests REST resource to update blanket and contract purchase agreements.

For example, you can use this REST API to update:
  • The start date or end date on purchase agreements
  • The price or supplier part number on a blanket purchase agreement line
  • The expiration date on a blanket purchase agreement line
  • The end date on a price break or create a new price break

Here's a typical application processing flow for the scenarios:

  1. You create a purchase agreement import request by including the updated agreement data. This step populates the interface tables with the agreement data
  2. You submit the purchase agreement import job.
  3. You view the status of the import job.
  4. If the agreement import wasn’t successful, you view the errors that occurred.
  5. You correct the errors and repeat the steps required.

Note:

See the Privileges topic for access requirements for this REST operation.

Create a Purchase Agreement Import Request

In this step, you populate the interface tables with the updated agreement data. Provide a Batch ID to identify the records that need to be processed.

This example provides a sample payload for end dating an existing price break while creating a new one.

Example URL

Use this resource URL format:

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.vision.adf.resourceitem+json" -d 'request payload' 
"https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests"

Example Request

Here's an example of the request body in JSON format:
{
    "BatchId": 115578,
    "ActionCode": "UPDATE",
    "ProcurementBU": "Vision Operations",
    "AgreementNumber": 1003301,
    "Supplier": "CV_SuppA01",
    "SupplierSite": "CVSuppA01Site01",
    "lines": [
        {
            "ActionCode": "SYNC",
            "LineNumber": 1,
            "priceBreaks": [
                {
                    "PriceBreakNumber": 1,
                    "EndDate": "2024-01-09"
                },
                {
                    "PriceBreakNumber": 2,
                    "ShipToLocation": "V1- New York City",
                    "ShipToOrganizationCode": "V1",
                    "Price": 90,
                    "StartDate": "2024-01-10"
                }
            ]
        }
    ]
}

Example Response

Here's an example of the response body in JSON format:
{
  "InterfaceHeaderId" : 300100590264653,
  "InterfaceHeaderKey" : null,
  "ActionCode" : "UPDATE",
  "BatchId" : 115578,
  "ImportSource" : null,
  "ApprovalActionCode" : "NONE",
  "AgreementHeaderId" : null,
  "AgreementNumber" : "1003301",
  "DocumentTypeCode" : null,
  "StyleId" : null,
  "Style" : null,
  "ProcurementBUId" : null,
  "ProcurementBU" : "Vision Operations",
  "BuyerId" : null,
  "Buyer" : null,
  "CurrencyCode" : null,
  "Description" : null,
  "SupplierId" : null,
  "Supplier" : "CV_SuppA01",
  "SupplierSiteId" : null,
  "SupplierSite" : "CVSuppA01Site01",
  "SupplierContactId" : null,
  "SupplierContact" : null,
  "FOB" : null,
  "CarrierId" : null,
  "Carrier" : null,
  "FreightTerms" : null,
  "PayOnReceiptFlag" : null,
  "PaymentTermsId" : null,
  "PaymentTerms" : null,
  "ChangeOrderDescription" : null,
  "ChangeOrderInitiatingParty" : null,
  "RequiredAcknowledgmentCode" : null,
  "SupplierOrder" : null,
  "AcknowledgmentWithinDays" : null,
  "SupplierCommunicationMethodCode" : null,
  "SupplierFax" : null,
  "SupplierEmailAddress" : null,
  "ConfirmingOrderFlag" : null,
  "AgreementAmount" : null,
  "AmountLimit" : null,
  "MinimumReleaseAmount" : null,
  "StartDate" : null,
  "EndDate" : null,
  "NoteToSupplier" : null,
  "NoteToReceiver" : null,
  "AutomaticallyGenerateOrdersFlag" : null,
  "AutomaticallySubmitForApprovalFlag" : null,
  "GroupRequisitionsFlag" : null,
  "GroupRequisitionLinesFlag" : null,
  "UseShipToOrganizationAndLocationFlag" : null,
  "UseNeedByDateFlag" : null,
  "CatalogAdministratorAuthoringFlag" : null,
  "ApplyPriceUpdatesToExistingOrdersFlag" : null,
  "CommunicatePriceUpdatesFlag" : null,
  "BuyerEmailAddress" : null,
  "ModeOfTransportCode" : null,
  "ModeOfTransport" : null,
  "ServiceLevelCode" : null,
  "ServiceLevel" : null,
  "AgingOnsetPointCode" : null,
  "AgingPeriodDays" : null,
  "ConsumptionAdviceFrequencyCode" : null,
  "ConsumptionAdviceSummaryCode" : null,
  "DefaultConsignmentLinesFlag" : null,
  "PayOnUseFlag" : null,
  "BillingCycleClosingDate" : null,
  "ConfigurationOrderingEnabledFlag" : null,
  "UseCustomerSalesOrderFlag" : null,
  "BuyerManagedTransportFlag" : null,
  "AllowOrderingFromUnassignedSitesFlag" : null,
  "OutsideProcessEnabledFlag" : null,
  "MasterContractNumber" : null,
  "MasterContractId" : null,
  "MasterContractTypeId" : null,
  "MasterContractType" : null,
  "UseOrderDateForOrderPricingFlag" : null,
  "AttributeCategory" : null,
  "Attribute1" : null,
  "Attribute2" : null,
  "Attribute3" : null,
  "Attribute4" : null,
  "Attribute5" : null,
  "Attribute6" : null,
  "Attribute7" : null,
  "Attribute8" : null,
  "Attribute9" : null,
  "Attribute10" : null,
  "Attribute11" : null,
  "Attribute12" : null,
  "Attribute13" : null,
  "Attribute14" : null,
  "Attribute15" : null,
  "Attribute16" : null,
  "Attribute17" : null,
  "Attribute18" : null,
  "Attribute19" : null,
  "Attribute20" : null,
  "AttributeDate1" : null,
  "AttributeDate2" : null,
  "AttributeDate3" : null,
  "AttributeDate4" : null,
  "AttributeDate5" : null,
  "AttributeDate6" : null,
  "AttributeDate7" : null,
  "AttributeDate8" : null,
  "AttributeDate9" : null,
  "AttributeDate10" : null,
  "AttributeNumber1" : null,
  "AttributeNumber2" : null,
  "AttributeNumber3" : null,
  "AttributeNumber4" : null,
  "AttributeNumber5" : null,
  "AttributeNumber6" : null,
  "AttributeNumber7" : null,
  "AttributeNumber8" : null,
  "AttributeNumber9" : null,
  "AttributeNumber10" : null,
  "AttributeTimestamp1" : null,
  "AttributeTimestamp2" : null,
  "AttributeTimestamp3" : null,
  "AttributeTimestamp4" : null,
  "AttributeTimestamp5" : null,
  "AttributeTimestamp6" : null,
  "AttributeTimestamp7" : null,
  "AttributeTimestamp8" : null,
  "AttributeTimestamp9" : null,
  "AttributeTimestamp10" : null,
  "CreatedBy" : "PRC_INTEGRATION_USER",
  "CreationDate" : "2024-01-17T07:39:09.022+00:00",
  "LastUpdatedBy" : "PRC_INTEGRATION_USER",
  "LastUpdateDate" : "2024-01-17T07:39:09.023+00:00",
  "ProcessCode" : null,
  "RequestId" : null,
  "lines" : [ {
    "InterfaceLineId" : 300100590264654,
    "InterfaceHeaderKey" : null,
    "InterfaceLineKey" : null,
    "ActionCode" : "SYNC",
    "LineNumber" : 1,
    "LineType" : null,
    "LineTypeId" : null,
    "Item" : null,
    "ItemId" : null,
    "ItemRevision" : null,
    "Category" : null,
    "CategoryId" : null,
    "ItemDescription" : null,
    "AgreementAmount" : null,
    "UOM" : null,
    "UOMCode" : null,
    "Price" : 120,
    "Amount" : null,
    "AllowPriceOverrideFlag" : null,
    "NotToExceedPrice" : null,
    "SupplierItem" : null,
    "NegotiatedFlag" : null,
    "NoteToReceiver" : null,
    "NoteToSupplier" : null,
    "MinimumReleaseAmount" : null,
    "SupplierPartAuxiliaryId" : null,
    "SupplierReferenceNumber" : null,
    "AgingPeriodDays" : null,
    "ConsignmentLineFlag" : null,
    "UnitWeight" : null,
    "WeightUOMCode" : null,
    "WeightUOMName" : null,
    "UnitVolume" : null,
    "VolumeUOMCode" : null,
    "VolumeUOMName" : null,
    "ParentItem" : null,
    "ParentItemId" : null,
    "TopModel" : null,
    "TopModelId" : null,
    "SupplierParentItem" : null,
    "SupplierTopModel" : null,
    "PriceBreakType" : null,
    "AllowDescriptionUpdateFlag" : null,
    "AttributeCategory" : null,
    "LineAttribute1" : null,
    "LineAttribute2" : null,
    "LineAttribute3" : null,
    "LineAttribute4" : null,
    "LineAttribute5" : null,
    "LineAttribute6" : null,
    "LineAttribute7" : null,
    "LineAttribute8" : null,
    "LineAttribute9" : null,
    "LineAttribute10" : null,
    "LineAttribute11" : null,
    "LineAttribute12" : null,
    "LineAttribute13" : null,
    "LineAttribute14" : null,
    "LineAttribute15" : null,
    "Attribute16" : null,
    "Attribute17" : null,
    "Attribute18" : null,
    "Attribute19" : null,
    "Attribute20" : null,
    "AttributeDate1" : null,
    "AttributeDate2" : null,
    "AttributeDate3" : null,
    "AttributeDate4" : null,
    "AttributeDate5" : null,
    "AttributeDate6" : null,
    "AttributeDate7" : null,
    "AttributeDate8" : null,
    "AttributeDate9" : null,
    "AttributeDate10" : null,
    "AttributeNumber1" : null,
    "AttributeNumber2" : null,
    "AttributeNumber3" : null,
    "AttributeNumber4" : null,
    "AttributeNumber5" : null,
    "AttributeNumber6" : null,
    "AttributeNumber7" : null,
    "AttributeNumber8" : null,
    "AttributeNumber9" : null,
    "AttributeNumber10" : null,
    "AttributeTimestamp1" : null,
    "AttributeTimestamp2" : null,
    "AttributeTimestamp3" : null,
    "AttributeTimestamp4" : null,
    "AttributeTimestamp5" : null,
    "AttributeTimestamp6" : null,
    "AttributeTimestamp7" : null,
    "AttributeTimestamp8" : null,
    "AttributeTimestamp9" : null,
    "AttributeTimestamp10" : null,
    "InterfaceHeaderId" : 300100590264653,
    "CreatedBy" : "PRC_INTEGRATION_USER",
    "CreationDate" : "2024-01-17T07:39:09.068+00:00",
    "LastUpdatedBy" : "PRC_INTEGRATION_USER",
    "LastUpdateDate" : "2024-01-17T07:39:09.068+00:00",
    "ProcessCode" : null,
    "RequestId" : null,
    "ExpirationDate" : null,
    "AgreementQuantity" : null,
    "priceBreaks" : [ {
      "InterfaceLineLocationId" : 300100590264655,
      "InterfaceLineKey" : null,
      "InterfaceLineLocationKey" : null,
      "PriceBreakNumber" : 1,
      "ShipToLocation" : null,
      "ShipToLocationId" : null,
      "ShipToOrganizationCode" : null,
      "ShipToOrganizationId" : null,
      "Quantity" : null,
      "Price" : 100,
      "DiscountPercent" : null,
      "StartDate" : null,
      "EndDate" : "2024-01-10",
      "Attribute1" : null,
      "Attribute10" : null,
      "Attribute11" : null,
      "Attribute12" : null,
      "Attribute13" : null,
      "Attribute14" : null,
      "Attribute15" : null,
      "Attribute16" : null,
      "Attribute17" : null,
      "Attribute18" : null,
      "Attribute19" : null,
      "Attribute2" : null,
      "Attribute20" : null,
      "Attribute3" : null,
      "Attribute4" : null,
      "Attribute5" : null,
      "Attribute6" : null,
      "Attribute7" : null,
      "Attribute8" : null,
      "Attribute9" : null,
      "AttributeCategory" : null,
      "AttributeDate1" : null,
      "AttributeDate10" : null,
      "AttributeDate2" : null,
      "AttributeDate3" : null,
      "AttributeDate4" : null,
      "AttributeDate5" : null,
      "AttributeDate6" : null,
      "AttributeDate7" : null,
      "AttributeDate8" : null,
      "AttributeDate9" : null,
      "AttributeNumber1" : null,
      "AttributeNumber10" : null,
      "AttributeNumber2" : null,
      "AttributeNumber3" : null,
      "AttributeNumber4" : null,
      "AttributeNumber5" : null,
      "AttributeNumber6" : null,
      "AttributeNumber7" : null,
      "AttributeNumber8" : null,
      "AttributeNumber9" : null,
      "AttributeTimestamp1" : null,
      "AttributeTimestamp10" : null,
      "AttributeTimestamp2" : null,
      "AttributeTimestamp3" : null,
      "AttributeTimestamp4" : null,
      "AttributeTimestamp5" : null,
      "AttributeTimestamp6" : null,
      "AttributeTimestamp7" : null,
      "AttributeTimestamp8" : null,
      "AttributeTimestamp9" : null,
      "CreatedBy" : "PRC_INTEGRATION_USER",
      "CreationDate" : "2024-01-17T07:39:09.077+00:00",
      "LastUpdatedBy" : "PRC_INTEGRATION_USER",
      "LastUpdateDate" : "2024-01-17T07:39:09.077+00:00",
      "ProcessCode" : null,
      "RequestId" : null,
      "links" : [ {
        "rel" : "self",
        "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654/child/priceBreaks/300100590264655",
        "name" : "priceBreaks",
        "kind" : "item",
        "properties" : {
          "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
        }
      }, {
        "rel" : "canonical",
        "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654/child/priceBreaks/300100590264655",
        "name" : "priceBreaks",
        "kind" : "item"
      }, {
        "rel" : "parent",
        "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654",
        "name" : "lines",
        "kind" : "item"
      } ]
    } ],
    "links" : [ {
      "rel" : "self",
      "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654",
      "name" : "lines",
      "kind" : "item",
      "properties" : {
        "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
      }
    }, {
      "rel" : "canonical",
      "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654",
      "name" : "lines",
      "kind" : "item"
    }, {
      "rel" : "parent",
      "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653",
      "name" : "purchaseAgreementImportRequests",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654/child/itemAttributes",
      "name" : "itemAttributes",
      "kind" : "collection"
    }, {
      "rel" : "child",
      "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654/child/priceBreaks",
      "name" : "priceBreaks",
      "kind" : "collection"
    }, {
      "rel" : "child",
      "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines/300100590264654/child/translationItemAttributes",
      "name" : "translationItemAttributes",
      "kind" : "collection"
    } ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653",
    "name" : "purchaseAgreementImportRequests",
    "kind" : "item",
    "properties" : {
      "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
    }
  }, {
    "rel" : "canonical",
    "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653",
    "name" : "purchaseAgreementImportRequests",
    "kind" : "item"
  }, {
    "rel" : "child",
    "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/businessUnitAccess",
    "name" : "businessUnitAccess",
    "kind" : "collection"
  }, {
    "rel" : "child",
    "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/child/lines",
    "name" : "lines",
    "kind" : "collection"
  }, {
    "rel" : "action",
    "href" : "https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653/action/importPurchaseAgreements",
    "name" : "importPurchaseAgreements",
    "kind" : "other"
  } ]
}

Submit the Purchase Agreement Import Request

After populating the interface tables, invoke a user-defined action to submit the purchase agreement import job. For invoking the user-defined action, specify the Batch ID and the required parameters, documentTypeCode, procurementBU, approvalActionCode, and defaultBuyer. The response returns a Request ID, which you can use to query the status of the import job and view errors, if any.

Example URL

Use this resource URL format:

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.vision.adf.resourceitem+json" -d 'request payload' 
"https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/InterfaceHeaderId"

For example:

curl -u username:password -X POST -H "Content-Type:application/vnd.vision.adf.resourceitem+json" -d 'request payload' 
"https://servername/fscmRestApi/resources/version/purchaseAgreementImportRequests/300100590264653"

Example Request

Here's an example of the request body in JSON format:
{
    "name": "importPurchaseAgreements",
    "parameters": [
        {
            "documentTypeCode": "BLANKET"
        },
        {
             "procurementBU": "Vision Operations"
        },
        {
             "defaultBuyer": " Furey,Clare"
        },
        {
             "approvalActionCode": "NONE"
        },
        {
             "batchId": "115578"
        }
    ]
}

Example Response

Here's an example of the response body in JSON format:
{
  "result" : "Request ID 158672 was submitted."
}

View the Status of the Import Job

After submitting the import job, you can check if the purchase agreement import job was successful by using the Request ID returned and invoking the ERP Integrations REST resource.

Example URL

Use this resource URL format:

GET

curl -u username:password "https://servername/fscmRestApi/resources/version/erpintegrations?finder=ESSJobStatusRF;requestId=RequestId"

For example:

curl -u username:password "https://servername/fscmRestApi/resources/version/erpintegrations?finder=ESSJobStatusRF;requestId=108893"

Example Response

Here's an example of the response body in JSON format:
{
    "items": [
        {
            "OperationName": "getESSJobStatus",
            "DocumentId": null,
            "DocumentContent": null,
            "FileName": null,
            "ContentType": null,
            "FileType": null,
            "DocumentAccount": null,
            "Comments": null,
            "ProcessName": null,
            "LoadRequestId": null,
            "JobPackageName": null,
            "JobDefName": null,
            "ReqstId": "108893",
            "RequestStatus": "SUCCEEDED",
            "JobName": null,
            "ParameterList": null,
            "NotificationCode": null,
            "CallbackURL": null,
            "JobOptions": null,
            "StatusCode": null,
            "ESSParameters": null,
            "links": [
                {
                    "rel": "self",
                    "href": "https://servername/fscmRestApi/resources/version/erpintegrations/getESSJobStatus",
                    "name": "erpintegrations",
                    "kind": "item"
                },
                {
                    "rel": "canonical",
                    "href": "https://servername/fscmRestApi/resources/version/erpintegrations/getESSJobStatus",
                    "name": "erpintegrations",
                    "kind": "item"
                }
            ]
        }
    ],
    "count": 1,
    "hasMore": false,
    "limit": 25,
    "offset": 0,
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/erpintegrations",
            "name": "erpintegrations",
            "kind": "collection"
        }
    ]
}

View Purchase Agreements Import Errors

To view errors, if any, that occurred while creating purchase agreements use the Request ID and invoke the Purchasing Document Import Errors REST resource.

Example URL

Use this resource URL format:

GET

curl -u username:password "https://servername/fscmRestApi/resources/version/purchasingDocumentImportErrors/InterfaceTransactionId"

For example:

curl -u username:password "https://servername/fscmRestApi/resources/version/purchasingDocumentImportErrors?q=RequestId=140824"

Example Response

Here's an example of the response body in JSON format:
{
  "items" : [ {
    "InterfaceTransactionId" : 44151,
    "InterfaceType" : "PO_DOCS_OPEN_INTERFACE",
    "BatchId" : 113347,
    "RequestId" : 140824,
    "ColumnName" : "VENDOR_SITE_CODE",
    "ColumnValue" : "CVSuppA01Site03",
    "ErrorMessage" : "The supplier site isn't valid. Verify that the site is active, has the purchasing purpose assigned, is associated with the procurement business unit, and has an active assignment for the requisitioning business unit.",
    "ErrorMessageName" : "PO_PDOI_SUPPLIER_SITE_VALID",
    "TableName" : "PO_GA_ORG_ASSIGN_INTERFACE",
    "InterfaceAssignmentId" : null,
    "InterfaceAttrValuesId" : null,
    "InterfaceAttrValuesTlpId" : null,
    "InterfaceDistributionId" : null,
    "InterfaceHeaderId" : 300100589306163,
    "InterfaceLineId" : null,
    "InterfaceLineLocationId" : null,
    "ProcessingDate" : "2024-01-09",
    "CreatedBy" : "CVBUYER01",
    "CreationDate" : "2024-01-09T09:08:04+00:00",
    "links" : [ {
      "rel" : "self",
      "href" : "https://servername/fscmRestApi/resources/version/purchasingDocumentImportErrors/00020000000EACED00057708000000000000AC7700000016504F5F444F43535F4F50454E5F494E54455246414345",
      "name" : "purchasingDocumentImportErrors",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "https://servername/fscmRestApi/resources/version/purchasingDocumentImportErrors/00020000000EACED00057708000000000000AC7700000016504F5F444F43535F4F50454E5F494E54455246414345",
      "name" : "purchasingDocumentImportErrors",
      "kind" : "item"
  
  } ],
  "count" : 1,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "https://servername/fscmRestApi/resources/version/purchasingDocumentImportErrors",
    "name" : "purchasingDocumentImportErrors",
    "kind" : "collection"
  } ]
}